home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr01 / jock.zip / TOTDOC11.ZIP / CHAPT11.TXT < prev    next >
Text File  |  1991-02-11  |  118KB  |  2,867 lines

  1.                                                                      Controlling
  2.                                                                             User
  3.                                                                            Input
  4.  
  5.  
  6.  
  7.          "I'm sick of writing documentation."              Bob Ainsbury
  8.  
  9.  
  10.  
  11.  
  12.  
  13. Introduction
  14.  
  15.          The Toolkit includes three major units to help you prompt the user for
  16.          input: totIO1, totIO2 and totIO3. These units provide more than 20
  17.          different input objects to accommodate all of your user input needs.
  18.          Objects may be used individually to prompt a user for input, or
  19.          combined together to build a powerful input form or dialog box.
  20.          There are objects to prompt for strings, numbers, dates, word-wrapping
  21.          memo fields, radio buttons, check boxes and lists. In the unlikely
  22.          event that there is no object type to support your specific needs, you
  23.          can create your own customized input objects.
  24.  
  25.  
  26.  
  27. Two Quick Examples
  28.          The Toolkit form input facilities are powerful and extensive, but you
  29.          don't need to understand every feature and facility to use them! Here
  30.          are a couple of examples to prove the point.
  31.  
  32.          The following example, DEMIO1.PAS, is a simple program which prompts
  33.          the user to enter a real number.
  34.          program DemoIOOne;
  35.          {demIO1 - single field input}
  36.  
  37.          Uses DOS, CRT,
  38.               totFAST, totIO1, totIO2;
  39.          Var
  40.             Price: FixedRealIOOBJ;
  41.  
  42.          begin
  43.             ClrScr;
  44.             with Price do
  45.             begin
  46.                Init(35,5,8,2);
  47.                SetLabel('How much was the doppleganger? ');
  48.                SetValue(250.0);
  49.                SetMinMax(0.1,12250.0);
  50.                SetRules(EraseDefault);
  51.                Activate;
  52.                Writeln;writeln('You entered ',GetValue);
  53.  
  54. 11-2                                                                User's Guide
  55. --------------------------------------------------------------------------------
  56.  
  57.                Done;
  58.             end;
  59.          end.
  60.  
  61.  
  62.          Let's analyze the program. At the top of the program is the declaration
  63.          of a variable called Price, which is of type FixedRealIOOBJ. All form
  64.          input fields have object names ending in "IOOBJ", which stands for
  65.          input-output object. The FixedRealIOOBJ object is for the input of real
  66.          numbers which have a fixed number of decimal places.
  67.          In the main part of the program, only the three bold statements are
  68.          mandatory. The Init statement initializes the field. The four parame-
  69.          ters represent the (X,Y) coordinate of the first character in the
  70.          field, the number of whole digits, and the number of decimal places,
  71.          respectively. In this example, the field will be located in column 35,
  72.          row 5, with 8 significant digits, and 2 decimal places. The Activate
  73.          command instructs the Toolkit to display the field and wait for user
  74.          input. The Done method disposes of the object.
  75.  
  76.          The other statements are used to customize the field. Any input field
  77.          can have a label, and usually, the label is displayed to the immediate
  78.          left of the field. The SetLabel method assigns a label to the input
  79.          field. By default, the field will have an initial value of zero. The
  80.          SetValue method is used to assign an initial default value of 250.0. As
  81.          you may have guessed, the SetMinMax method ensures that the user inputs
  82.          a number within a specified range. Figure 11.1 shows the error message
  83.          generated by the user when an invalid number is entered. The SetRules
  84.          method instructs the Toolkit to erase the default value if the user
  85.          first presses a non-editing key, e.g. a number.
  86.          The function method GetValue returns the value entered by the user.
  87.  
  88.  
  89. Figure 11.1                                                             [SCREEN]
  90. Automatic Input
  91. Validation
  92.  
  93.  
  94.          The second example, DEMIO2.PAS, shows how to combine a number of fields
  95.          into a full screen input form:
  96.  
  97.          program DemoIOTwo;
  98.          {demIO2 - full field input}
  99.          Uses DOS, CRT,
  100.               totFAST, totIO1, totIO2;
  101.  
  102.  
  103.  
  104. Controlling User Input                                                      11-3
  105. --------------------------------------------------------------------------------
  106.  
  107.          Var
  108.             Name: LateralIOOBJ;
  109.             Phone: PictureIOOBJ;
  110.             Price: FixedRealIOOBJ;
  111.             Keys: ControlkeysIOOBJ;
  112.             Manager: FormOBJ;
  113.             Result: tAction;
  114.  
  115.          procedure InitVars;
  116.          {}
  117.          begin
  118.             with Name do
  119.             begin
  120.                Init(35,5,20,40);
  121.                SetLabel('Vendor Name');
  122.             end;
  123.             with Phone do
  124.             begin
  125.                Init(35,7,'(###) ###-####');
  126.                SetLabel('Tel');
  127.             end;
  128.             with Price do
  129.             begin
  130.                Init(35,9,8,2);
  131.                SetLabel('Unit Price');
  132.                SetValue(250.0);
  133.                SetMinMax(0.1,12250.0);
  134.                SetRules(EraseDefault);
  135.             end;
  136.             Keys.Init;
  137.          end; {InitVars}
  138.          begin
  139.             ClrScr;
  140.             Screen.TitledBox(15,3,65,11,76,79,78,2,' Quicky Input Demo ');
  141.             Screen.WriteCenter(25,white,'Press TAB to switch fields and
  142.                                          press ESC or F10 to end');
  143.             InitVars;
  144.             with Manager do
  145.             begin
  146.                Init;
  147.                AddItem(Keys);
  148.                AddItem(Name);
  149.                AddItem(Phone);
  150.                AddItem(Price);
  151.                Result := Go;
  152.                if Result = Finished then
  153.                   {update the database..}
  154.                else
  155.  
  156.  
  157.  
  158. 11-4                                                                User's Guide
  159. --------------------------------------------------------------------------------
  160.  
  161.                   {call Esc routine};
  162.             end;
  163.          end.
  164.  
  165.  
  166.          In this example, there are three input fields which prompt the user to
  167.          input a name, a telephone number and a unit price. The object Keys, of
  168.          type ControlKeysIOOBJ, is used to control which keys allow the user to
  169.          switch between fields and terminate the input session. By default, the
  170.          following keys are supported [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP].
  171.          Every full screen input form must be controlled by a form manager of
  172.          type FormOBJ. In the example, the instance Manager is used.
  173.  
  174.          The procedure InitVars is called to initialize all the input fields
  175.          using methods similar to the ones used in the previous example. In the
  176.          body of the main program, the Manager instance is initialized, and each
  177.          of the IO objects is included in the form by calling the method AddI-
  178.          tem. Finally, the function method Go is called to instruct the Toolkit
  179.          to process user input. The method returns a member of the enumerated
  180.          type tAction, which indicates whether the user escaped or ended nor-
  181.          mally - in this case by pressing [KEYCAP].
  182.          Figure 11.2 illustrates the output generated by this program. Note that
  183.          the first field can literally scroll, allowing the user to input data
  184.          which is longer than the visible field.
  185.  
  186.  
  187. Figure 11.2                                                             [SCREEN]
  188. Full Screen
  189. Input
  190.  
  191.  
  192.  
  193. The Object Hierarchy
  194.          The totIO units make extensive use of inheritance and polymorphism, and
  195.          this is reflected in the object hierarchy (see figure 11.3).
  196.  
  197.  
  198.  
  199. Controlling User Input                                                      11-5
  200. --------------------------------------------------------------------------------
  201.  
  202. Figure 11.3
  203. totIO
  204. Object Hierarchy
  205.  
  206.  
  207.  
  208. 11-6                                                                User's Guide
  209. --------------------------------------------------------------------------------
  210.  
  211.          At first, the object hierarchy may seem daunting, but there really
  212.          isn't much to it. Many of the objects are abstract, and these are
  213.          shaded gray in the figure. Remember that you should not create
  214.          instances of abstract objects -- use a descendant.
  215.  
  216.          All you have to decide is which object fits your input needs, and then
  217.          create an instance. For example, if you want to prompt a user for a
  218.          date, use the DateIOOBJ, or if you want to prompt for a number, choose
  219.          RealIOOBJ, FixedRealIOOBJ, or IntIOOBJ.
  220.          It is often difficult to determine which methods are applicable to
  221.          which objects, especially with a deeply structured object hierarchy.
  222.          Part 3: Flash Cards lists, in one place, all the methods available for
  223.          each object in the IO hierarchy.
  224.  
  225.          Listed below is a brief description of each input object:
  226.          StringIOOBJ       Basic string input. Provides methods to force the
  227.                            case of text, and to justify text when the user moves
  228.                            to another field.
  229.  
  230.          PictureIOOBJ      String input which supports a special field mask or
  231.                            picture to control input. The following special
  232.                            format characters govern input:
  233.                            !          Forces letters to upper case
  234.                            #          Only accepts numbers
  235.                            @          Only accepts letters and punctuation
  236.                            *          Accepts any character
  237.  
  238.                            For example, the field mask '(###) ###-####' is ideal
  239.                            for US telephone numbers.
  240.          LateralIOOBJ      String input which supports lateral scrolling. For
  241.                            example, the field width can be set to 20 characters
  242.                            wide, but the user might be allowed to enter up to 40
  243.                            characters.
  244.  
  245.          DateIOOBJ         Input of dates. The Toolkit supports eight different
  246.                            date formats, and this field will automatically
  247.                            verify that the date entered is valid, and, option-
  248.                            ally, within a specified range.
  249.          IntIOOBJ          Whole number input. Use this object when you want to
  250.                            obtain a whole number, i.e. shortint, byte, integer,
  251.                            word, longint. Provides methods to ensure input is
  252.                            within a specified range.
  253.  
  254.          RealIOOBJ         Real number input. By using Toolkit compiler direc-
  255.                            tives (discussed on page 3.9), this object can get
  256.                            input of single, double, extended, and comp reals.
  257.                            Provides methods to ensure input is within a speci-
  258.                            fied range.
  259.  
  260.  
  261.  
  262.  
  263. Controlling User Input                                                      11-7
  264. --------------------------------------------------------------------------------
  265.  
  266.          FixedRealIOOBJ    Like RealIOOBJ, this object is for the input of real
  267.                            numbers. The object is similar to contemporary data-
  268.                            base packages - there are a fixed number of decimal
  269.                            places, and when the user presses [KEYCAP] the cursor
  270.                            jumps to the right of the decimal place.
  271.  
  272.          HexIOOBJ          Just for the engineers, this accepts the input of
  273.                            hexadecimal numbers!
  274.          WWArrayIOOBJ      A multi-line word-wrapping field. A one-dimensional
  275.                            string array is assigned to the field. The contents
  276.                            of the array are updated with the user's input.
  277.  
  278.          WWLinkIOOBJ       Also a multi-line word-wrapping field. A DLLOBJ
  279.                            instance is assigned to the field. The linked list is
  280.                            updated with the user's input.
  281.          ArrayIOOBJ        A scrollable list of options from which the user may
  282.                            select one. The displayed list is based on the
  283.                            contents of a one-dimensional string array.
  284.  
  285.          LinkIOOBJ         A scrollable list based on the contents of a DLLOBJ
  286.                            instance.
  287.          CheckIOOBJ        A check box field, where the user can check any item
  288.                            in the list.
  289.  
  290.          RadioIOOBJ        A radio button field where the user can select any
  291.                            one item in the list.
  292.          StripIOOBJ        A "Turbo 6.0 like" button which the user can select,
  293.                            e.g. buttons for Edit, Save, Cancel, etc.
  294.  
  295.          Strip3dIOOBJ      The same as StripIOOBJ, except that a small 3-D
  296.                            shadow is drawn behind the strip.
  297.          ButttonIOOBJ      A "Norton Utilities-like" box button.
  298.  
  299.          HotKeyIOOBJ       HotkeyIOOBJ are invisible fields, used to trap for
  300.                            special keys. For example, the key [KEYCAP] might
  301.                            terminate the input session.
  302.          ControlKeysIOOBJ  Defines which keys are used to move between fields,
  303.                            and which keys terminate the input session.
  304.  
  305.  
  306.          Figure 11.4 shows a not-so-useful screen which uses every input type!
  307.          The on-disk demo file DEMIO3.PAS created the display.
  308.  
  309.  
  310.  
  311.            Note: All the display colors used by the input objects are con-
  312.            trolled by the global instance pointer IOTOT. IOTOT controls all
  313.            the common display characteristics for input fields. This makes it
  314.  
  315. 11-8                                                                User's Guide
  316. --------------------------------------------------------------------------------
  317.  
  318.            easy to change the overall look and feel of your program, by just
  319.            changing the IOTOT values. IOTOT will be discussed in detail later
  320.            in the chapter (page 11-40).
  321.  
  322.  
  323. Figure 11.4                                                             [SCREEN]
  324. Every Field
  325. Type
  326.  
  327.  
  328. Common Field Methods
  329.  
  330.          All the Toolkit IO objects are derived from the base object ItemIOOBJ.
  331.          This abstract object defines the following fundamental methods which
  332.          are shared by all the objects:
  333.  
  334.          SetActiveStatus(Selectable:boolean);
  335.  
  336.          The Toolkit allows you to display fields in a form which are not always
  337.          accessible, i.e. the user cannot land the cursor on the field. Fields
  338.          which are displayed, but cannot be highlighted, are referred to as
  339.          inactive fields. By default, all fields are active, but the method
  340.          SetActiveStatus can be used to control activity status. Pass True to
  341.          activate the field, or False to deactivate it.
  342.  
  343.          SetHotkey(HK:word);
  344.  
  345.          Every field can be optionally selected by pressing a Hotkey. You can
  346.          assign a hotkey to any field with the method SetHotKey. The passed
  347.          parameter is the Toolkit key code (refer to the table on page 6-3) that
  348.          represents the key which will activate the field. For example, the
  349.          statement SetHotKey(305) assigns the key [KEYCAP] to the object. When
  350.          the user presses [KEYCAP], the cursor will jump to this field. Be sure
  351.          to assign different hotkeys to each field. To inform the user of the
  352.          hotkey, you can use the SetLabel method with the embedded character '~'
  353.          to highlight the key, e.g. SetLabel('~N~ame');.
  354.  
  355.          SetID(ID:word);
  356.  
  357.          By default, every field has an ID of zero. You can assign each field a
  358.          different ID with the SetID method. This ID is used to indicate the
  359.          highlighted field when a user presses a help function, or when a field
  360.          raises a signal to indicate that other fields need to be refreshed. The
  361.          topics of Help and Signals are discussed later.
  362.  
  363.          In addition to these basic methods, all visible fields share the fol-
  364.          lowing two methods:
  365.  
  366.  
  367.  
  368. Controlling User Input                                                      11-9
  369. --------------------------------------------------------------------------------
  370.  
  371.          SetLabel(Lbl:string);
  372.  
  373.          Every visible field can have a label. The label is usually displayed to
  374.          the immediate left of the input field. When the field is highlighted,
  375.          the label is drawn in a different color to signify that the field is
  376.          active. Use the SetLabel command to specify a string label for any
  377.          field. Note that the use of the embedded control character '~' is sup-
  378.          ported. Refer to the discussion of the Screen.WriteHi method on page
  379.          5-3 for further information.
  380.  
  381.          SetMessage(X,Y:byte; Msg:string);
  382.  
  383.          The Toolkit can display an optional message at some location on the
  384.          screen when the field is highlighted. When the user leaves the field,
  385.          the message is erased. (Note: the old screen contents which were cov-
  386.          ered by the message are not restored.) Use the SetMessage method to
  387.          identify the location of the message and the message text.
  388.  
  389.          Listed below is the demo program DEMIO4.PAS, which is a variation on
  390.          the program DEMIO2.PAS, discussed earlier. The usability has been
  391.          enhanced by adding informative (!) messages, and the user can jump to
  392.          the various fields by pressing hotkeys. Figure 11.5 shows the resultant
  393.          display.
  394.  
  395.          program DemoIOFour;
  396.          {demIO4 - using hotkeys, labels, and messages}
  397.          Uses DOS, CRT,
  398.               totFAST, totIO1, totIO2;
  399.  
  400.          Var
  401.             Name: LateralIOOBJ;
  402.             Phone: PictureIOOBJ;
  403.             Price: FixedRealIOOBJ;
  404.             Keys: ControlkeysIOOBJ;
  405.             Manager: FormOBJ;
  406.             Result: tAction;
  407.          procedure InitVars;
  408.          {}
  409.          begin
  410.             with Name do
  411.             begin
  412.                Init(35,5,20,40);
  413.                SetLabel('Vendor ~N~ame');
  414.                SetHotkey(305); {Alt-N}
  415.                SetMessage(22,11,'Enter the vendor''s name, 40 chars Max');
  416.             end;
  417.             with Phone do
  418.             begin
  419.  
  420.  
  421.  
  422. 11-10                                                               User's Guide
  423. --------------------------------------------------------------------------------
  424.  
  425.                Init(35,7,'(###) ###-####');
  426.                SetLabel('~T~el');
  427.                SetHotkey(276); {Alt-T}
  428.                SetMessage(22,11,'Enter the vendor''s phone number');
  429.             end;
  430.             with Price do
  431.             begin
  432.                Init(35,9,8,2);
  433.                SetLabel('Unit ~P~rice');
  434.                SetHotKey(281); {Alt-P}
  435.                SetMessage(22,11,'Enter the unit price in dollars');
  436.             end;
  437.             Keys.Init;
  438.          end; {InitVars}
  439.  
  440.          begin
  441.             ClrScr;
  442.             Screen.TitledBox(15,3,65,12,76,79,78,2,' Quicky Input Demo ');
  443.             Screen.WriteCenter(25,white,'Press TAB to switched fields and press
  444.          ESC or F10 to end');
  445.             InitVars;
  446.             with Manager do
  447.             begin
  448.                Init;
  449.                AddItem(Keys);
  450.                AddItem(Name);
  451.                AddItem(Phone);
  452.                AddItem(Price);
  453.                Result := Go;
  454.                if Result = Finished then
  455.                   {update the database..}
  456.                else
  457.                   {call Esc routine};
  458.             end;
  459.          end.
  460.  
  461.  
  462.  
  463. Figure 11.5                                                             [SCREEN]
  464. Using Labels &
  465. Messages
  466.  
  467.  
  468. Field Types
  469.  
  470.          The Object hierarchy illustrates the interrelated nature of the totIO
  471.          objects. The objects are loosely organized into the following groups:
  472.  
  473.  
  474.  
  475. Controlling User Input                                                     11-11
  476. --------------------------------------------------------------------------------
  477.  
  478.                 String       StringIOOBJ        (totIO2)
  479.                              PictureIOOBJ       (totIO2)
  480.                              LateralIOOBJ       (totIO2)
  481.  
  482.                 Number       IntIOOBJ           (totIO2)
  483.                              RealIOOBJ          (totIO2)
  484.                              FixedRealIOOBJ     (totIO2)
  485.                              HexIOOBJ           (totIO2)
  486.                 Date         DateIOOBJ          (totIO2)
  487.  
  488.                 Check/Radio  CheckIOOBJ         (totIO1)
  489.                              RadioIOOBJ         (totIO1)
  490.                 Lists        ArrayIOOBJ         (totIO2)
  491.                              LinkIOOBJ          (totIO2)
  492.  
  493.                 Wordwrap     WWArrayIOOBJ       (totIO3)
  494.                              WWLinkIOOBJ        (totIO3)
  495.                 Buttons      StripIOOBJ         (totIO1)
  496.                              Strip3dIOOBJ       (totIO1)
  497.                              ButtonIOOBJ        (totIO1)
  498.  
  499.                 Hotkeys      HotkeyIOOBJ        (totIO1)
  500.                              ControlKeysIOOBJ   (totIO1)
  501.  
  502.  
  503.          The objects which fall into the category of single line objects are the
  504.          String, Number and Date object groups. These objects are similar in
  505.          nature, and share the following common methods:
  506.  
  507.          SetIns(InsOn: boolean);
  508.  
  509.          Pass True to set the field initially in insert mode, or False to be in
  510.          overtype mode.
  511.  
  512.          SetRules(Rules:byte);
  513.  
  514.          The rules control some of the field's editing properties. The following
  515.          constants are declared in the totIO1 unit:
  516.          NoRules         This is the default state, with no editing rules
  517.                          active.
  518.  
  519.          AllowNull       Use this rule to instruct the Toolkit to accept an
  520.                          empty or null number field, even though the SetMinMax
  521.                          method has been used to confine the acceptable input
  522.                          within a range.
  523.          SuppressZero    This rule suppresses the display of the default field
  524.                          value in number fields, when the value is zero, i.e.
  525.                          the field is empty, rather than showing "0" or "0.0".
  526.  
  527. 11-12                                                               User's Guide
  528. --------------------------------------------------------------------------------
  529.  
  530.          EraseDefault    When active, this rule forces the emptying of the
  531.                          field's default value, when a user highlights the field
  532.                          and presses a non-editing key.
  533.  
  534.          JumpIfFull      This rule forces the user to the next field, as soon as
  535.                          the current field is filled.
  536.          To specify multiple rules, simply sum the rules. For example, the
  537.          following statement will enforce three of the rules:
  538.  
  539.                SetRules(AllowNull+EraseDefault+JumpIfFull);
  540.  
  541.  
  542.          SetDispChar(Ch:char);
  543.          Normally, the key pressed by the user is displayed in the input field.
  544.          However, for security, you may want to echo a different character to
  545.          the screen. Use this method to suppress the display of the typed char-
  546.          acters. The Toolkit will use the character Ch to identify that a char-
  547.          acter has been pressed. This method is ideal for password fields. Note
  548.          that the field stores the actual typed characters, as this method only
  549.          affects the way the display is updated. Pass a character of ' ' (space)
  550.          to instruct the Toolkit to echo the typed characters.
  551.  
  552.  
  553.          SetPadChar(Pad:char);
  554.          This method controls which character is used to pad out the empty part
  555.          of the input field. By default, the character used is defined in the
  556.          IOTOT object (discussed later).
  557.  
  558.  
  559.          With the exception of the FixedRealIOOBJ, the single line input fields
  560.          also share the following two methods:
  561.  
  562.          SetJust(Just:tJust);
  563.  
  564.          When the user leaves the current field, the Toolkit can automatically
  565.          justify the field data. This method controls the justification. The
  566.          totSTR unit includes the declaration of an enumerated type tJust, which
  567.          has the following members:  JustLeft, JustCenter and JustRight. (Sounds
  568.          like a good name for a breakfast cereal!) By default, fields are left
  569.          justified.
  570.  
  571.          SetCursor(Curs:tCursPos);
  572.  
  573.          Every time the user jumps to a new field, the Toolkit has to decide
  574.          where to position the cursor. This method controls the cursor position-
  575.          ing for each field. The totIO1 unit includes the declaration of an
  576.          enumerated type tJust, which has the following members: CursLeft,
  577.          CursRight and CursPrev. Use CursLeft and CursRight to force the cursor
  578.  
  579.  
  580.  
  581.  
  582. Controlling User Input                                                     11-13
  583. --------------------------------------------------------------------------------
  584.  
  585.          to the leftmost or rightmost character position respectively. The Cur-
  586.          sPrev setting (default) instructs the Toolkit to position the cursor
  587.          where it was the last time the field was edited.
  588.  
  589.  
  590. String Fields
  591.  
  592.          The three string field objects (StringIOOBJ, PictureIOOBJ and Lateral-
  593.          IOOBJ) are all located in the totIO2 unit. All these objects are
  594.          descended from the abstract object VisibleIOOBJ, and share the
  595.          following methods, which were described earlier:
  596.                   SetActiveStatus(Selectable:boolean);
  597.                   SetHotkey(HK:word);
  598.                   SetID(ID:word);
  599.                   SetLabel(Lbl:string);
  600.                   SetMessage(X,Y:byte;Msg:string);
  601.                   Activate;
  602.  
  603.          In addition, the following methods are shared by all three objects:
  604.  
  605.          SetCase(Cas:tCase);
  606.  
  607.          The totSTR unit includes the declaration of an enumerated type tCase
  608.          which has the following members: Lower, Upper, Proper and Leave. This
  609.          method can be used to control whether the Toolkit automatically adjusts
  610.          the case field string when the user leaves the field. Set the case to
  611.          Leave if you want the string to remain the same case as when it was
  612.          entered.
  613.  
  614.          SetForceCase(On:boolean);
  615.  
  616.          The SetForceCase method is used to control whether the case of the
  617.          string input is adjusted while the user is typing in the string. Pass a
  618.          True parameter to force the case adjustment (as specified with the
  619.          method SetCase) every time a character is pressed. Pass a False parame-
  620.          ter if you want the string to be adjusted only when the user moves to
  621.          another field.
  622.  
  623.          SetValue(Str:string);
  624.  
  625.          This method assigns a default value to the field. This value will be
  626.          displayed when the field is first displayed.
  627.  
  628.          GetValue: string;
  629.  
  630.          This method should be called (after the user has completed the input
  631.          session) to determine which string was entered.
  632.  
  633.  
  634.  
  635.  
  636. 11-14                                                               User's Guide
  637. --------------------------------------------------------------------------------
  638.  
  639.          Done;
  640.  
  641.          This method disposes of the memory consumed by the object, and should
  642.          be called after all user input is completed.
  643.  
  644.  
  645. StringIOOBJ
  646.          The StringIOOBJ is used to obtain string input from the user. The user
  647.          may enter any alphanumeric character, including upper ASCII and inter-
  648.          national characters. The only method specific to StringIOOBJ is the
  649.          important Init method. The syntax of Init is as follows:
  650.  
  651.  
  652.          Init(X,Y,FieldLen:byte);
  653.          This method must be called first. The first two parameters indicate the
  654.          (X,Y) coordinate of the first character in the field. The third parame-
  655.          ter specifies the field length.
  656.  
  657.  
  658.  
  659. LateralIOOBJ
  660.          The LateralIOOBJ object is very similar to StringIOOBJ, except that the
  661.          field can scroll horizontally, allowing the user to input more charac-
  662.          ters than are visible in the field. LateralIOOBJ has its own Init
  663.          method as follows:
  664.  
  665.  
  666.          Init(X,Y,Fieldlen,MaxLen:byte);
  667.          This method must be called first. The first two parameters indicate the
  668.          (X,Y) coordinate of the first character in the field, the third parame-
  669.          ter specifies the visible field length, and the fourth parameter speci-
  670.          fies the maximum length of the input string, i.e. the scrollable field
  671.          length.
  672.  
  673.  
  674.  
  675. PictureIOOBJ
  676.          The PictureIOOBJ object gives you character by character control of the
  677.          input data, and allows you to embed non-editable characters into the
  678.          field.
  679.  
  680.          When you initialize the object using the Init method (discussed later),
  681.          you must specify a string which represents the field picture. The pic-
  682.          ture is comprised of non-editable characters and the following four,
  683.          pre-defined, format characters:
  684.             #     Allows the input of the characters (0-9 . -) and indicates
  685.                   that only numbers may be input.
  686.  
  687.  
  688.  
  689. Controlling User Input                                                     11-15
  690. --------------------------------------------------------------------------------
  691.  
  692.             @     Allows only letters of the English alphabet and punctuation
  693.                   characters.
  694.  
  695.             *     Allows any character the user can find.
  696.             !     Converts all alphabetical characters to upper case.
  697.  
  698.          Any other characters embedded in the picture are treated as fixed and
  699.          for display only.
  700.          For example, the picture '(###) ###-####' would be used for the input
  701.          of US telephone numbers, and the picture '@@@####' might be used for a
  702.          seven character part number which comprises three letters and four dig-
  703.          its.
  704.  
  705.          The field picture is specified in the Init method as follows:
  706.  
  707.          Init(X,Y:byte; Picture:string);
  708.  
  709.          This method must be called first. The first two parameters indicate the
  710.          (X,Y) coordinate of the first character in the field, and the third
  711.          parameter specifies the field picture.
  712.  
  713.          Two other methods are provided to give even more control over which
  714.          characters can be input. You can either specify the characters which
  715.          are allowable, or the characters which are not allowable. The following
  716.          two methods serve this purpose:
  717.  
  718.  
  719.          SetDisAllowChar(Str:string);
  720.          When this method is used, the Toolkit will not allow the user to input
  721.          any of the characters specified in the Str. For example, SetDisAllow-
  722.          Char('\:'); will not allow the user to input a backslash or colon,
  723.          regardless of the field picture.
  724.  
  725.  
  726.          SetAllowChar(Str:string);
  727.          This method is the opposite of the previous one, and it is used to
  728.          identify all the characters which the Toolkit will allow the user to
  729.          enter. For example, SetAllowChar('AaBbCc0123456789'); will only allow
  730.          the user to input numbers, or the characters A, B and C.
  731.  
  732.  
  733.          Only use one or the other of these methods. If you only want to stop
  734.          the user from entering a few specific characters, use SetDisAllowChar.
  735.          On the other hand, if you only want to allow a few characters to be
  736.          input, use the SetAllowChar method.
  737.  
  738.  
  739.  
  740. 11-16                                                               User's Guide
  741. --------------------------------------------------------------------------------
  742.  
  743.          The function method GetValue will return the condensed string excluding
  744.          the format characters. For example, a telephone number would be
  745.          returned as 10 digits with no brackets or spaces. The following method
  746.          will return the fully formatted string, including all embedded format
  747.          characters:
  748.  
  749.  
  750.          GetPicValue:string;
  751.          Returns the string entered by the user, including all formatting char-
  752.          acters.
  753.  
  754.  
  755.  
  756.            Note: the totStr unit includes the function PicFormat which
  757.            returns a formatted string. Refer to chapter 14: String Handling
  758.            for further information.
  759.  
  760.  
  761.  
  762.  
  763. String Field Examples
  764.          Listed below is an extract of the demo program DEMIO5, which focuses on
  765.          string fields. Figure 11.6 shows an example of the display generated by
  766.          the full program.
  767.  
  768.          procedure InitVars;
  769.          {}
  770.          begin
  771.             with Field1 do
  772.             begin
  773.                Init(40,3,10);
  774.                SetLabel('Field 1  (StringIOOBJ)');
  775.             end;
  776.             with Field2 do
  777.             begin
  778.                Init(40,5,10);
  779.                SetLabel('Field 2  (StringIOOBJ)');
  780.                SetCase(upper);
  781.                SetValue('hello');
  782.                SetRules(EraseDefault+JumpIfFull);
  783.             end;
  784.             with Field3 do
  785.             begin
  786.                Init(40,7,15,30);
  787.                SetLabel('Field 3 (LateralIOOBJ)');
  788.             end;
  789.             with Field4 do
  790.             begin
  791.                Init(40,9,15,30);
  792.  
  793.  
  794. Controlling User Input                                                     11-17
  795. --------------------------------------------------------------------------------
  796.  
  797.                SetLabel('Field 4 (LateralIOOBJ)');
  798.                SetCase(Upper);
  799.                SetForcecase(True);
  800.                SetCursor(CursLeft);
  801.             end;
  802.             with Field5 do
  803.             begin
  804.                Init(40,11,'(###) ###-####');
  805.                SetLabel('Field 5 (PictureIOOBJ)');
  806.             end;
  807.             with Field6 do
  808.             begin
  809.                Init(40,13,'!!!***@@@###');
  810.                SetLabel('Field 6 (PictureIOOBJ)');
  811.                SetDisAllowChar('aAbBcC123@!');
  812.                SetRules(EraseDefault);
  813.             end;
  814.             with Field7 do
  815.             begin
  816.                Init(40,15,10);
  817.                SetLabel('Field 7  (StringIOOBJ)');
  818.                SetDispChar('#');
  819.             end;
  820.          end; {InitVars}
  821.  
  822.  
  823. Figure 11.6                                                             [SCREEN]
  824. Using String
  825. Fields
  826.  
  827.  
  828.          Don't forget that IO objects can be used individually, to prompt the
  829.          user with a single field. Listed below is the demo program DEMIO6.PAS,
  830.          which prompts the user to enter a string.
  831.          program DemoIOSix;
  832.          {demIO6 - single string field input}
  833.  
  834.          Uses DOS, CRT,
  835.               totFAST, totIO1, totIO2, totSTR;
  836.          var
  837.            Field: StringIOOBJ;
  838.  
  839.          begin
  840.             with Field do
  841.             begin
  842.                Init(40,5,10);
  843.                SetLabel('Field (StringIOOBJ)');
  844.                SetCase(upper);
  845.                SetValue('hello');
  846.  
  847.  
  848. 11-18                                                               User's Guide
  849. --------------------------------------------------------------------------------
  850.  
  851.                SetRules(EraseDefault+JumpIfFull);
  852.                clrscr;
  853.                Activate;
  854.                writeln;writeln('You entered ',GetValue);
  855.                Done;
  856.             end;
  857.          end.
  858.  
  859.  
  860.  
  861.  
  862. Number Fields
  863.          The totIO2 unit includes the following four objects for creating number
  864.          fields: IntIOOBJ, RealIOOBJ, FixedRealIOOBJ and HEXIOOBJ. All these
  865.          objects are descended from the abstract object CharIOOBJ, and share the
  866.          following methods which were described earlier:
  867.  
  868.                   SetActiveStatus(Selectable:boolean);
  869.                   SetHotkey(HK:word);
  870.                   SetID(ID:word);
  871.                   SetLabel(Lbl:string);
  872.                   SetMessage(X,Y:byte;Msg:string);
  873.                   SetIns(InsOn:boolean);
  874.                   SetRules(Rules:byte);
  875.                   SetDispChar(Ch:char);
  876.                   SetPadChar(Pad:char);
  877.                   Activate;
  878.                   Done;
  879.  
  880.          Except for FixedRealIOOBJ, the number fields also support the following
  881.          two methods:
  882.  
  883.                   SetJust(Just:tJust);
  884.                   SetCursor(Curs:tCursPos);
  885.  
  886.  
  887. IntIOOBJ
  888.          The IntIOOBJ object should be used to prompt for whole numbers, i.e.
  889.          with a type of byte, word, shortint, integer and longint. The following
  890.          additional methods are supported by IntIOOBJ objects:
  891.  
  892.  
  893.          Init(X,Y,Len:byte);
  894.          This method must be called first. The first two parameters indicate the
  895.          (X,Y) coordinate of the first character in the field. The third parame-
  896.          ter specifies the field length.
  897.  
  898.  
  899.          SetMinMax(Min,Max:longint);
  900.  
  901.  
  902.  
  903. Controlling User Input                                                     11-19
  904. --------------------------------------------------------------------------------
  905.  
  906.          The Toolkit can automatically ensure that the user input falls within a
  907.          specified range. Use the method SetMinMax to set an input range. Pass
  908.          two zeros to turn off input validation. If the user tries to input an
  909.          invalid value, the Toolkit displays a pop-up message explaining the
  910.          problem (see figure 11.1), and forces the user to input a valid number.
  911.  
  912.  
  913.          SetValue(Val:longint);
  914.          Use this method to set an initial or default value in the field.
  915.  
  916.  
  917.          GetValue: longint;
  918.          This function method returns the value input by the user.
  919.  
  920.  
  921.  
  922. RealIOOBJ
  923.          This object is very similar to IntIOOBJ, except that it is designed for
  924.          the input of real numbers, i.e. numbers with one or more decimal
  925.          places.
  926.  
  927.  
  928.            Note: The Toolkit supports all the real types, i.e. real, single,
  929.            double, extended and comp. By default, all these types are mapped
  930.            to the base type REAL. In other words, if you declare a variable
  931.            of type EXTENDED, the Toolkit re-maps it so that Turbo Pascal
  932.            treats it like a basic REAL. If you do want to support all the
  933.            additional precision reals, edit the file TOTFLAGS.INC and adjust
  934.            the conditional defines FLOAT and FLOATEM.  Refer to page 3-9 for
  935.            further information.
  936.  
  937.          In addition to the common methods, the following methods are supported
  938.          by RealIOOBJ objects:
  939.  
  940.  
  941.          Init(X,Y,Len:byte);
  942.          This method must be called first. The first two parameters indicate the
  943.          (X,Y) coordinate of the first character in the field. The third parame-
  944.          ter specifies the field length.
  945.  
  946.  
  947.          SetMinMax(Min,Max:extended);
  948.          The Toolkit can automatically ensure that the user input falls within a
  949.          specified range. Use the method SetMinMax to set an input range. Pass
  950.          two zeros to suppress input validation. If the user tries to input an
  951.          invalid value, the Toolkit displays a pop-up message explaining the
  952.          problem (see figure 11.1), and forces the user to input a valid number.
  953.  
  954.  
  955.  
  956.  
  957. 11-20                                                               User's Guide
  958. --------------------------------------------------------------------------------
  959.  
  960.          SetValue(Val:extended);
  961.  
  962.          Use this method to set an initial or default value in the field.
  963.  
  964.          SetENotation(On:boolean);
  965.  
  966.          This method controls whether the user is allowed to enter the number in
  967.          E-notation, e.g. 4.435623E+12. Pass True to allow the user to input
  968.          E-notation, or False to disallow it.
  969.  
  970.          GetValue: extended;
  971.  
  972.          This function method returns the value input by the user.
  973.  
  974.  
  975. FixedRealIOOBJ
  976.  
  977.          You may have used some commercial database or financial software pro-
  978.          grams which provide special cursor control when the user is inputting
  979.          real numbers. For example, when the user presses [KEYCAP], the cursor
  980.          automatically jumps to the right of the fixed decimal place. The Fixe-
  981.          dRealIOOBJ object brings this capability to the Toolkit. (The cursor
  982.          and key reactions emulate the FoxPro database package - we liked it, so
  983.          we copied it!)
  984.          FixedRealIOOBJ objects provide the following additional methods:
  985.  
  986.  
  987.          Init(X,Y,Whole,DP:byte);
  988.          This method must be called first. The first two parameters indicate the
  989.          (X,Y) coordinate of the first character in the field. The third parame-
  990.          ter specifies the maximum number of whole numbers, and the last parame-
  991.          ter specifies the maximum number of decimal places.
  992.  
  993.  
  994.          SetMinMax(Min,Max:extended);
  995.          The Toolkit can automatically ensure that the user input falls within a
  996.          specified range. Use the method SetMinMax to set an input range. Pass
  997.          two zeros to suppress input validation. If the user tries to input an
  998.          invalid value, the Toolkit displays a pop-up message explaining the
  999.          problem (see figure 11.1), and forces the user to input a valid number.
  1000.  
  1001.  
  1002.          SetValue(Val:extended);
  1003.          Use this method to set an initial or default value in the field.
  1004.  
  1005.  
  1006.          GetValue: extended;
  1007.          This function method returns the value input by the user.
  1008.  
  1009. Controlling User Input                                                     11-21
  1010. --------------------------------------------------------------------------------
  1011.  
  1012. HEXIOOBJ
  1013.  
  1014.          If you want a user to enter HEX numbers, HEXIOOBJ is the object for
  1015.          you. HEXIOOBJ is very similar to IntIOOBJ, with the main difference
  1016.          that HEX allows the user to input numbers and the letters A, B, C, D, E
  1017.          and F.
  1018.          As well as the common number methods, HEXIOOBJ supports the following
  1019.          methods:
  1020.  
  1021.  
  1022.          Init(X,Y,Len:byte);
  1023.          This method must be called first. The first two parameters indicate the
  1024.          (X,Y) coordinate of the first character in the field. The third parame-
  1025.          ter specifies the field length.
  1026.  
  1027.  
  1028.          SetMinMax(Min,Max:longint);
  1029.          The Toolkit can automatically ensure that the user input falls within a
  1030.          specified range. Use the method SetMinMax to set an input range. Pass
  1031.          two zeros to turn off input validation.
  1032.  
  1033.  
  1034.          SetValue(Val:longint);
  1035.          Use this method to set an initial or default value in the field.
  1036.  
  1037.  
  1038.          GetValue: longint;
  1039.          This function method returns the value input by the user.
  1040.  
  1041.  
  1042.  
  1043.            Note: in Turbo Pascal HEX numbers are preceded by a '$' character.
  1044.            For example, the following method calls have the same effect:
  1045.                               SetValue($FF);
  1046.                               SetValue(255);
  1047.  
  1048.  
  1049.  
  1050.  
  1051. Formatting Number Fields
  1052.          The objects IntIOOBJ, RealIOOBJ and FixedREALIOOBJ all provide optional
  1053.          formatting capabilities, which can be used to control the format of the
  1054.          displayed number when the user leaves the field, i.e. when the user is
  1055.          editing, the number is unformatted, but when the user exits the field,
  1056.          the number can be formatted in a variety of styles. For example, the
  1057.          number -123456.78 might be formatted as $123,456.78 CR.
  1058.  
  1059.          If you want formatted number fields, you must call the following
  1060.          method:
  1061.  
  1062. 11-22                                                               User's Guide
  1063. --------------------------------------------------------------------------------
  1064.  
  1065.          InitFormat;
  1066.  
  1067.          This method instructs the object to format the field when the user
  1068.          leaves the field.
  1069.  
  1070.          The totSTR unit includes the object FmtNumberOBJ, which is designed to
  1071.          format numbers. The FmtNumber object includes the following methods:
  1072.  
  1073.                   SetPrefixSuffix(P,S:char);
  1074.                   SetSign(S:tSign);
  1075.                   SetSeparators(P,T,D:char);
  1076.                   SetJustification(J:tJust);
  1077.  
  1078.          These methods are described in detail in chapter 14: String Handling.
  1079.          Refer to this chapter for further information.
  1080.  
  1081.          Behind the scenes, when the number method InitFormat is called, the
  1082.          Toolkit creates a private FmtNumberOBJ instance. The number method For-
  1083.          matPtr can be used to access the FmtNumberOBJ instance using the fol-
  1084.          lowing syntax:
  1085.                   FormatPtr^.[method]
  1086.  
  1087.          For example, the following code fragment formats an integer field with
  1088.          a '$' prefix and embedded commas.
  1089.                   var
  1090.                     Field: IntIOOBJ;
  1091.  
  1092.                   begin
  1093.                      with Field do
  1094.                      begin
  1095.                         Init;
  1096.                         InitFormat;
  1097.                         FormatPtr^.SetPrefixSuffix('$',#0);
  1098.                         FormatPtr^.SetSeparators(' ',',','.');
  1099.                         {...}
  1100.                      end;
  1101.                   end.
  1102.  
  1103.  
  1104.  
  1105. Setting the Default Format
  1106.  
  1107.          The totIO2 unit includes FmtNumberTOT, a pointer to an object instance
  1108.          of type FmtNumberOBJ. This instance defines the default formatting that
  1109.          will be applied to real and integer fields during full-screen input.
  1110.          Whenever a number field object's method InitFormat is called, the
  1111.          field's initial formats are copied from FmtNumberTOT.
  1112.  
  1113.  
  1114.  
  1115. Controlling User Input                                                     11-23
  1116. --------------------------------------------------------------------------------
  1117.  
  1118.          You can control each field's default value by setting FmtNumberTOT to
  1119.          specifically meet your needs, before you call the InitFormat method.
  1120.          For example, if you want all your number fields to be formatted with a
  1121.          suffix of FR, set the default with the following statement:
  1122.  
  1123.                   FmtNumberTOT.SetPrefixSuffix('','FR');
  1124.          All number objects initialized after this statement will assume the FR
  1125.          suffix.
  1126.  
  1127.  
  1128.  
  1129. Number Field Examples
  1130.          Back on the first page of this chapter you saw an example of how to
  1131.          prompt the user for a real number using FixedRealIOOBJ. Take another
  1132.          look at page 11.1 and see if the statements make more sense now!
  1133.  
  1134.          Listed below is an extract of the demo program DEMIO8.PAS which illus-
  1135.          trates how to use many of the methods discussed in this section. Figure
  1136.          11.7 shows an example of the display generated by the full program.
  1137.          procedure InitVars;
  1138.          {}
  1139.          begin
  1140.             with Field1 do
  1141.             begin
  1142.                Init(40,3,5);
  1143.                SetLabel('Field 1  (IntIOOBJ)');
  1144.             end;
  1145.             with Field2 do
  1146.             begin
  1147.                Init(40,5,5);
  1148.                InitFormat;
  1149.                SetLabel('Field 2  (IntIOOBJ)');
  1150.                SetValue(69);
  1151.                SetRules(EraseDefault+JumpIfFull);
  1152.             end;
  1153.             with Field3 do
  1154.             begin
  1155.                Init(40,7,10);
  1156.                SetLabel('Field 3 (RealIOOBJ)');
  1157.             end;
  1158.             with Field4 do
  1159.             begin
  1160.                Init(40,9,15);
  1161.                InitFormat;
  1162.                FormatPtr^.SetSeparators('*',',','.');
  1163.                FormatPtr^.SetPrefixSuffix('','FR');
  1164.                FormatPtr^.SetJustification(JustRight);
  1165.                SetLabel('Field 4 (RealIOOBJ)');
  1166.  
  1167.  
  1168. 11-24                                                               User's Guide
  1169. --------------------------------------------------------------------------------
  1170.  
  1171.                SetCursor(CursLeft);
  1172.             end;
  1173.             with Field5 do
  1174.             begin
  1175.                Init(40,11,8,2);
  1176.                SetLabel('Field 5 (FixedRealIOOBJ)');
  1177.             end;
  1178.             with Field6 do
  1179.             begin
  1180.                Init(40,13,5);
  1181.                SetLabel('Field 6  (HEXIOOBJ)');
  1182.             end;
  1183.             Keys.Init;
  1184.          end; {InitVars}
  1185.  
  1186.  
  1187. Figure 11.7                                                             [SCREEN]
  1188. Using Number
  1189. Fields
  1190.  
  1191.  
  1192.  
  1193. Date Fields
  1194.          The DateIOOBJ object is used to prompt the user to input a date. The
  1195.          Toolkit supports eight different date formats. The totDATE unit
  1196.          includes an enumerated type tDate which has the following members:
  1197.          MMDDYY, MMDDYYY, MMYY, MMYYYY, DDMMYY, DDMMYYYY, YYMMDD, YYYYMMDD.
  1198.          Whenever you work with dates, you must identify the desired date for-
  1199.          mat.
  1200.  
  1201.          Refer to chapter 13: Managing Dates for a full description of all the
  1202.          date manipulation routines which complement DateIOOBJ. There are a
  1203.          wealth of functions to convert dates to and from Julian, Gregorian and
  1204.          string formats. For example, the JultoStr and StrtoJul functions con-
  1205.          vert between Julian and string formats.
  1206.          DateIOOBJ is a descendant of CharIOOBJ, and inherits the following,
  1207.          previously described, methods:
  1208.  
  1209.                   SetActiveStatus(Selectable:boolean);
  1210.                   SetHotkey(HK:word);
  1211.                   SetID(ID:word);
  1212.                   SetLabel(Lbl:string);
  1213.                   SetMessage(X,Y:byte;Msg:string);
  1214.                   SetIns(InsOn:boolean);
  1215.                   SetRules(Rules:byte);
  1216.                   SetDispChar(Ch:char);
  1217.                   SetPadChar(Pad:char);
  1218.                   Activate;
  1219.                   Done;
  1220.  
  1221.  
  1222. Controlling User Input                                                     11-25
  1223. --------------------------------------------------------------------------------
  1224.  
  1225.          The DateIOOBJ object manipulates dates in Julian format, where dates
  1226.          are specified as longints. DateIOOBJ includes the following methods:
  1227.  
  1228.  
  1229.          Init(X,Y:byte; DateFmt:tDate);
  1230.          This method must be called first. The first two parameters indicate the
  1231.          (X,Y) coordinate of the first character in the field. The third parame-
  1232.          ter is a member of the enumerated type tDate, and indicates which for-
  1233.          mat of date is to be input, e.g. MMDDYY or DDMMYY.
  1234.  
  1235.  
  1236.          SetMinMax(Min,Max:longint);
  1237.          The Toolkit will automatically verify if proper dates are entered, i.e.
  1238.          that the month is between 1 and 12, and the days are valid for the
  1239.          specified month. The method SetMinMax can also be used to specify a
  1240.          date range. Pass two zeros to turn off input validation. If the user
  1241.          tries to input an invalid date or an out of range date, the Toolkit
  1242.          displays a pop-up message explaining the problem (see figure 11.8), and
  1243.          forces the user to input a valid number.
  1244.  
  1245.  
  1246.          SetValue(Date: longint);
  1247.          Use this method to set an initial or default value in the field. The
  1248.          date is passed as a Julian (longint) value.
  1249.  
  1250.  
  1251.          GetValue:longint;
  1252.          This function method returns the Julian date value input by the user.
  1253.  
  1254.  
  1255.          Listed below is the demo program DEMIO9.PAS which prompts the user for
  1256.          the input of a single date. Figure 11.8 is an example of the date
  1257.          validation performed by the Toolkit.
  1258.  
  1259.          program DemoIONine;
  1260.          {demIO9 - single date field input}
  1261.          Uses DOS, CRT,
  1262.               totIO1, totIO2, totDate;
  1263.  
  1264.          Var
  1265.             Birthday: DateIOOBJ;
  1266.          begin
  1267.             ClrScr;
  1268.             with Birthday do
  1269.             begin
  1270.                Init(35,5,MMDDYY);
  1271.                SetLabel('When is your next birthday? ');
  1272.                Activate;
  1273.  
  1274.  
  1275. 11-26                                                               User's Guide
  1276. --------------------------------------------------------------------------------
  1277.  
  1278.                Writeln;
  1279.                writeln('You entered the Julian date',GetValue);
  1280.                writeln('i.e. ',JultoStr(GetValue,MMDDYY));
  1281.                Done;
  1282.             end;
  1283.          end.
  1284.  
  1285.  
  1286. Figure 11.8                                                             [SCREEN]
  1287. Single Date
  1288. Input
  1289.  
  1290.  
  1291.          Listed below is an extract of the demo program DEMIO10.PAS which illus-
  1292.          trates how to use many of the methods discussed in this section. Figure
  1293.          11.9 shows an example of the display generated by the full program.
  1294.          procedure InitVars;
  1295.          {}
  1296.          begin
  1297.             with Field1 do
  1298.             begin
  1299.                Init(40,3,MMDDYY);
  1300.                SetLabel('Field 1   (MMDDYY)');
  1301.             end;
  1302.             with Field2 do
  1303.             begin
  1304.                Init(40,5,MMDDYY);
  1305.                SetLabel('Field 2   (MMDDYY)');
  1306.                SetValue(TodayInJul);
  1307.                SetRules(EraseDefault+JumpIfFull);
  1308.             end;
  1309.             with Field3 do
  1310.             begin
  1311.                Init(40,7,DDMMYYYY);
  1312.                SetLabel('Field 3 (DDMMYYYY)');
  1313.              end;
  1314.             with Field4 do
  1315.             begin
  1316.                Init(40,9,DDMMYYYY);
  1317.                SetLabel('Field 4 (DDMMYYYY)');
  1318.                SetMinMax(GregtoJul(3,1,1992),GregtoJul(3,31,1992));
  1319.                SetCursor(CursLeft);
  1320.              end;
  1321.             Keys.Init;
  1322.          end; {InitVars}
  1323.  
  1324.  
  1325.  
  1326. Controlling User Input                                                     11-27
  1327. --------------------------------------------------------------------------------
  1328.  
  1329. Figure 11.9                                                             [SCREEN]
  1330. Using Date
  1331. Fields
  1332.  
  1333.  
  1334.  
  1335. Check Boxes and Radio Buttons
  1336.          Two common elements of contemporary input forms are check boxes and
  1337.          radio buttons. Both these objects provide ways of choosing items from
  1338.          lists of options. Figure 11.10 (listed later in the section) illus-
  1339.          trates both types of objects.
  1340.  
  1341.          A check box object provides a list of options with each item having its
  1342.          own check box displayed to the left of the item, e.g. [X] Toast. Any
  1343.          number of items in the list can be selected. An item's selection status
  1344.          is toggled by hitting the [KEYCAP] or by clicking the mouse cursor on
  1345.          it. Selected items have an X in the adjacent check box.
  1346.          Radio buttons are similar to check boxes, except that only one item can
  1347.          be selected. When an item is selected, the previously selected item is
  1348.          deselected. The selected item has a dot in the "button" next to it,
  1349.          e.g. (.) Ham Sandwich.
  1350.  
  1351.          The Toolkit objects CheckIOOBJ and RadioIOOBJ are located in the totIO1
  1352.          unit, and are descended from VisibleIOOBJ. Both objects, therefore,
  1353.          inherit the following, previously described, methods:
  1354.                   SetActiveStatus(Selectable:boolean);
  1355.                   SetHotkey(HK:word);
  1356.                   SetID(ID:word);
  1357.                   SetLabel(Lbl:string);
  1358.                   SetMessage(X,Y:byte;Msg:string);
  1359.                   Activate;
  1360.                   Done;
  1361.  
  1362.  
  1363.          The objects are part of the MultLineIOOBJ object family and also
  1364.          inherit the following method:
  1365.  
  1366.          SetBoxOn(On:boolean);
  1367.  
  1368.          All multi-line objects can be optionally displayed in a box. By
  1369.          default, the objects are not displayed in a box. To activate the box
  1370.          display, pass a True parameter.
  1371.  
  1372.          Both objects share the following common methods:
  1373.  
  1374.  
  1375.          Init(X1,Y1,width,depth:byte; Title:string);
  1376.  
  1377.  
  1378.  
  1379. 11-28                                                               User's Guide
  1380. --------------------------------------------------------------------------------
  1381.  
  1382.          This method should be called first. The first two parameters specify
  1383.          the (X,Y) coordinate of the top left of the object. The third and
  1384.          fourth parameters specify the width and depth of the object in charac-
  1385.          ters. The width should be large enough to accommodate the longest item,
  1386.          and leave room for the box, if the box is active. The depth should be
  1387.          large enough to accommodate the title, all the items and, optionally,
  1388.          the box.
  1389.  
  1390.  
  1391.          AddItem(Str:string; HK:word; Selected:boolean);
  1392.          This method adds an item to the list. The first parameter specifies the
  1393.          text to be displayed - don't forget that embedded '~' characters can be
  1394.          used to highlight text (see page 5-3 for further information). The
  1395.          second parameter is an optional hot key code, which the user can press
  1396.          to jump to this item and automatically select/deselect it. Pass a value
  1397.          of zero if you don't want to specify a hotkey. The third parameter
  1398.          indicates whether the item is selected or not. You can add as many
  1399.          items as will fit in the object's initialized dimensions.
  1400.  
  1401.  
  1402.  
  1403.            Note: the generic method SetHotKey is used to specify the hotkey
  1404.            for the entire object. If the user presses the generic hotkey, the
  1405.            object will be selected, and the last active item will be high-
  1406.            lighted. The individual item hotkeys allow the user to both select
  1407.            the object, and immediately activate the specific item. The demo
  1408.            program DEMIO12.PAS, discussed later, illustrates hotkeys.
  1409.  
  1410.  
  1411.  
  1412. CheckIOOBJ
  1413.  
  1414.          CheckIOOBJ provides the following two methods for setting and checking
  1415.          the status of each item:
  1416.  
  1417.          SetValue(Item:byte; selected:boolean);
  1418.  
  1419.          This method is used to change the selection status of an item after it
  1420.          has been added with AddItem. The first parameter specifies the item
  1421.          number, and the second boolean parameter should be set to True to
  1422.          select the item, or false to deselect it.
  1423.  
  1424.          GetValue(Item:byte):boolean;
  1425.  
  1426.          This boolean function method returns True if the specified item is
  1427.          selected.
  1428.  
  1429.  
  1430.  
  1431. Controlling User Input                                                     11-29
  1432. --------------------------------------------------------------------------------
  1433.  
  1434. RadioIOOBJ
  1435.  
  1436.          RadioIOOBJ has the following methods for setting and checking which
  1437.          item is selected:
  1438.  
  1439.          SetValue(Item:byte);
  1440.  
  1441.          Only one item in a radio button object can be selected. Use this method
  1442.          (after you have added all the items) to specify which item is selected.
  1443.  
  1444.          GetValue:byte;
  1445.  
  1446.          This function returns the number of the selected item.
  1447.  
  1448.  
  1449. Examples
  1450.  
  1451.          Listed below is the demo program DEMIO11.PAS illustrating a single
  1452.          radio button field.
  1453.          program DemoIOEleven;
  1454.          {demIO11 - single Radio Button input}
  1455.  
  1456.          Uses DOS, CRT,
  1457.               totFAST, totINPUT, totIO1, totIO2;
  1458.          Var
  1459.             Bool: RadioIOOBJ;
  1460.  
  1461.          begin
  1462.             ClrScr;
  1463.             with Bool do
  1464.             begin
  1465.                Init(35,12,20,5,'Sex?');
  1466.                SetBoxOn(True);
  1467.                AddItem('~M~ale',77,true);
  1468.                AddItem('~F~emale',70,false);
  1469.                Mouse.Show;
  1470.                Activate;
  1471.                Mouse.Hide;
  1472.                gotoxy(1,20);
  1473.                if GetValue = 1 then
  1474.                   writeln('You are male!')
  1475.                else
  1476.                   writeln('Hi, I''m Bob.');
  1477.                Done;
  1478.             end;
  1479.          end.
  1480.  
  1481.  
  1482.  
  1483. 11-30                                                               User's Guide
  1484. --------------------------------------------------------------------------------
  1485.  
  1486.          Listed below is an extract of the demo program DEMIO12.PAS, which
  1487.          illustrates how to combine mulitiple fields in a dialog box. Figure
  1488.          11.10 shows an example of the display generated by the full program.
  1489.  
  1490.          procedure InitVars;
  1491.          {}
  1492.          begin
  1493.             with Field1 do
  1494.             begin
  1495.                Init(17,5,25,4,'Options');
  1496.                AddItem('~C~ase sensitive',67,false);
  1497.                AddItem('~W~hole words only',87,false);
  1498.                AddItem('~R~egular expression',82,false);
  1499.             end;
  1500.             with Field2 do
  1501.             begin
  1502.                Init(17,10,25,3,'Scope');
  1503.                AddItem('~G~lobal',71,true);
  1504.                AddItem('~S~elected text',83,false);
  1505.             end;
  1506.             with Field3 do
  1507.             begin
  1508.                Init(45,5,17,3,'Direction');
  1509.                AddItem('Forwar~d~',68,true);
  1510.                AddItem('~B~ackward',66,false);
  1511.             end;
  1512.             with Field4 do
  1513.             begin
  1514.                Init(45,10,17,3,'Origin');
  1515.                AddItem('~F~rom cursor',70,false);
  1516.                AddItem('~E~ntire scope',69,true);
  1517.             end;
  1518.             Keys.Init;
  1519.          end; {InitVars}
  1520.  
  1521. Figure 11.10                                                            [SCREEN]
  1522. A Custom
  1523. Dialog Box
  1524.  
  1525.  
  1526.  
  1527. List Fields
  1528.          Radio buttons allow the user to select a single item from a list.
  1529.          Sometimes, however, you may have too many items in the list to display
  1530.          all together. The ListOOBJ object family can be used to display scroll-
  1531.          able lists, and these are located in the totIO2 unit.
  1532.  
  1533.  
  1534.  
  1535. Controlling User Input                                                     11-31
  1536. --------------------------------------------------------------------------------
  1537.  
  1538.          ListIOOBJ is an abstract object, and you should only use the descen-
  1539.          dants ArrayIOOBJ and LinkIOOBJ. These objects display the contents of a
  1540.          string array and a DLLOBJ linked list, respectively. Both these objects
  1541.          are descendant from MultiLineIOOBJ, and inherit the following, pre-
  1542.          viously discussed, methods:
  1543.  
  1544.                   SetActiveStatus(Selectable:boolean);
  1545.                   SetHotkey(HK:word);
  1546.                   SetID(ID:word);
  1547.                   SetLabel(Lbl:string);
  1548.                   SetMessage(X,Y:byte;Msg:string);
  1549.                   SetBoxOn(On:boolean);
  1550.                   Activate;
  1551.                   Done;
  1552.  
  1553.          Both items share the following common Init method:
  1554.  
  1555.  
  1556.          Init(X1,Y1,width,depth:byte; Title:string);
  1557.          This method should be called first. The first two parameters specify
  1558.          the (X,Y) coordinate of the top left of the object. The third and
  1559.          fourth parameters specify the width and depth of the object in charac-
  1560.          ters. The width should be large enough to accommodate the longest item,
  1561.          a scroll bar (if there are too many items to display at once) and leave
  1562.          room for the box (if the box is active). The depth should be large
  1563.          enough to accommodate the title, at least one item and, optionally, the
  1564.          box.
  1565.  
  1566.  
  1567.          Having initialized the object, the next task is to call the AssignList
  1568.          method. AssignList instructs the Toolkit where to locate the data for
  1569.          the items in the list. Each object has its own AssignList method.
  1570.  
  1571.  
  1572. ArrayIOOBJ
  1573.          The Toolkit gets the contents of the list from a string array, which
  1574.          you must create separately. Having created the array, you must call the
  1575.          following method:
  1576.  
  1577.  
  1578.          AssignList(var StrArray; Total:longint; StrLength:byte);
  1579.          AssignList identifies the string array that will be displayed. The four
  1580.          parameters are the string array, the total number of elements in the
  1581.          array, and the length of each string in the array. The string length
  1582.          parameter must reflect the string length of the array when it was
  1583.          declared, not the maximum length of any string assigned to the array.
  1584.  
  1585.  
  1586.  
  1587. 11-32                                                               User's Guide
  1588. --------------------------------------------------------------------------------
  1589.  
  1590.          Listed below is the demo program DEMIO13.PAS, which illustrates how to
  1591.          build an ArrayIOOBJ field.
  1592.  
  1593.          program DemoIOThirteen;
  1594.          {demIO13 - single ArrayIOOBJ input}
  1595.  
  1596.          Uses DOS, CRT,
  1597.               totFAST, totIO1, totIO2;
  1598.          Var
  1599.             MyList: array[1..10] of string[20];
  1600.             ListField: ArrayIOOBJ;
  1601.  
  1602.          procedure FillArray;
  1603.          {}
  1604.          begin
  1605.             MyList[1] := 'Monitor';
  1606.             MyList[2] := 'Keyboard';
  1607.             MyList[3] := 'Mouse';
  1608.             MyList[4] := 'Light Pen';
  1609.             MyList[5] := 'Microphone';
  1610.             MyList[6] := 'LCD O/H Panel';
  1611.             MyList[7] := 'Modem';
  1612.             MyList[8] := 'Printer';
  1613.             MyList[9] := 'CD Rom';
  1614.             MyList[10] := 'Toolkit';
  1615.          end; {FillArray}
  1616.          begin
  1617.             ClrScr;
  1618.             FillArray;
  1619.             with ListField do
  1620.             begin
  1621.                Init(35,5,15,6,'Peripherals');
  1622.                AssignList(MyList,10,20);
  1623.                Activate;
  1624.                gotoxy(1,20);
  1625.                writeln('You chose item: ',GetValue,' - ',MyList[GetValue]);
  1626.                Done;
  1627.             end;
  1628.          end.
  1629.  
  1630.  
  1631.  
  1632.  
  1633. LinkIOOBJ
  1634.          This object accesses a DLLOBJ object, to determine which items to dis-
  1635.          play in the list. You must create a DLLOBJ instance, populate the list,
  1636.          and then call the following AssignList method:
  1637.  
  1638.  
  1639.  
  1640. Controlling User Input                                                     11-33
  1641. --------------------------------------------------------------------------------
  1642.  
  1643.          AssignList(var LinkList: DLLOBJ);
  1644.  
  1645.          This method is passed a DLLOBJ instance, or any instance of an object
  1646.          descended from DLLOBJ, e.g. StrDLLOBJ.
  1647.  
  1648.          Listed below is the demo program DEMIO14.PAS, which illustrates how to
  1649.          build a LinkIOOBJ field.
  1650.  
  1651.          program DemoIOFourteen;
  1652.          {demIO14 - single LinkIOOBJ input}
  1653.  
  1654.          Uses DOS, CRT,
  1655.               totFAST, totIO1, totIO2, totLINK;
  1656.          Var
  1657.             MyList: StrDLLOBJ;
  1658.             ListField: LinkIOOBJ;
  1659.  
  1660.          procedure FillList;
  1661.          {}
  1662.          var Retcode: integer;
  1663.          begin
  1664.             with MyList do
  1665.             begin
  1666.                Init;
  1667.                Retcode := Add('Monitor');
  1668.                Retcode := Add('Keyboard');
  1669.                Retcode := Add('Mouse');
  1670.                Retcode := Add('Light Pen');
  1671.                Retcode := Add('Microphone');
  1672.                Retcode := Add('LCD O/H Panel');
  1673.                Retcode := Add('Modem');
  1674.                Retcode := Add('Printer');
  1675.                Retcode := Add('CD Rom');
  1676.                Retcode := Add('Toolkit');
  1677.             end;
  1678.          end; {FillList}
  1679.          begin
  1680.             ClrScr;
  1681.             FillList;
  1682.             with ListField do
  1683.             begin
  1684.                Init(35,5,15,6,'Peripherals');
  1685.                AssignList(MyList);
  1686.                Activate;
  1687.                gotoxy(1,20);
  1688.                writeln('You chose item: ',GetValue,' - ',
  1689.                        MyList.GetStr(MyList.NodePtr(GetValue),0,0));
  1690.                Done;
  1691.  
  1692.  
  1693.  
  1694. 11-34                                                               User's Guide
  1695. --------------------------------------------------------------------------------
  1696.  
  1697.                MyList.Done;
  1698.             end;
  1699.          end.
  1700.  
  1701.  
  1702.  
  1703.          Both the examples produce identical displays, see figure 11.11 below.
  1704.  
  1705.  
  1706. Figure 11.11                                                            [SCREEN]
  1707. Displaying
  1708. a List
  1709.  
  1710.  
  1711.  
  1712. Word Wrapping Fields
  1713.          Some of the most powerful, but easy to use, form objects are the Word-
  1714.          WrapIOOBJ objects. These objects can be used to display scrollable memo
  1715.          fields. The user can type in multiple lines of text with full editing,
  1716.          and the object provides automatic word wrapping.
  1717.  
  1718.          WordWrapIOOBJ is an abstract object, and you should only use the
  1719.          descendants WWArrayIOOBJ and WWLinkIOOBJ. Like the List objects
  1720.          described in the last section, these objects display the contents of a
  1721.          string array and a DLLOBJ linked list, respectively. Both objects are
  1722.          descendant from MultiLineIOOBJ, and inherit the following, previously
  1723.          discussed, methods:
  1724.                   SetActiveStatus(Selectable:boolean);
  1725.                   SetHotkey(HK:word);
  1726.                   SetID(ID:word);
  1727.                   SetLabel(Lbl:string);
  1728.                   SetMessage(X,Y:byte;Msg:string);
  1729.                   SetBoxOn(On:boolean);
  1730.                   SetIns(InsOn:boolean);
  1731.                   Activate;
  1732.                   Done;
  1733.  
  1734.  
  1735.          Both items share the following common Init method:
  1736.  
  1737.          Init(X1,Y1,width,lines:byte; Title:string);
  1738.  
  1739.          This method should be called first. The first two parameters specify
  1740.          the (X,Y) coordinate of the top left of the object. The third parameter
  1741.          specifies the width of the object in characters, and the fourth parame-
  1742.          ter specifies the number of lines of text to display. The last parame-
  1743.          ter is an optional title.
  1744.  
  1745.  
  1746.  
  1747. Controlling User Input                                                     11-35
  1748. --------------------------------------------------------------------------------
  1749.  
  1750.          Having initialized the object, the next task is to call the AssignList
  1751.          method. AssignList instructs the Toolkit where to locate the data for
  1752.          the text. Each object has its own AssignList method, and these are
  1753.          explained in a later section.
  1754.  
  1755.          If you want to pre-load the field with some text, you can take advan-
  1756.          tage of the following auto-word wrapping method:
  1757.  
  1758.          WrapFull;
  1759.  
  1760.          This method adjusts the contents of the source data structure, i.e. the
  1761.          string array or linked list, by word wrapping the existing text. When
  1762.          you add text to the data structures you do not need to accurately word
  1763.          wrap the text, but you should make sure that there is always one space
  1764.          at the end of the line. This space separates the last word on one line
  1765.          from the first word on the next line.
  1766.  
  1767.          Sometimes, you may want to display a word wrap field, but not allow the
  1768.          user to edit the text. The following method controls whether editing is
  1769.          allowed:
  1770.  
  1771.  
  1772.          SetAllowEdit(On:Boolean);
  1773.          Pass true to enable editing (default). When editing is disabled, the
  1774.          user may still scroll the text, but it cannot be changed.
  1775.  
  1776.  
  1777.          When the word wrap fields are used on their own, i.e. by calling acti-
  1778.          vate rather than as part of a form, the user can end the input by
  1779.          pressing F10. This "end edit" key can be assigned to another key using
  1780.          the following method:
  1781.  
  1782.          SetEndKey(K:word);
  1783.  
  1784.          Specifies the key which will end the input session when the field is
  1785.          used individually rather than as part of a form. The default is F10.
  1786.  
  1787.  
  1788. WWArrayIOOBJ
  1789.          The Toolkit gets the text contents from a string array, which you must
  1790.          create separately. Having created the array, you must call the follow-
  1791.          ing method:
  1792.  
  1793.  
  1794.          AssignList(var StrArray; Total:longint; StrLength:byte);
  1795.  
  1796.  
  1797.  
  1798. 11-36                                                               User's Guide
  1799. --------------------------------------------------------------------------------
  1800.  
  1801.          AssignList identifies the string array that will be displayed. The
  1802.          three parameters are the string array, the total number of elements in
  1803.          the array, and the length of each string in the array. The string
  1804.          length parameter must reflect the string length of the array when it
  1805.          was declared, not the maximum length of any string assigned to the
  1806.          array.
  1807.  
  1808.  
  1809.  
  1810.            Note: the Toolkit is unable to extend the size of the array. You
  1811.            must, therefore, ensure the array is large enough to accommodate
  1812.            all the text the user is allowed to enter. If you want an unlim-
  1813.            ited number of lines, or you want the Toolkit to extend the lines
  1814.            used, take advantage of the WWlinkOBJ described next.
  1815.  
  1816.  
  1817.  
  1818.          Listed below is the demo program DEMIO15.PAS, which illustrates how to
  1819.          build an WWArrayIOOBJ field.
  1820.          program DemoIOFifteen;
  1821.          {demIO15 - single WWArrayIOOBJ input}
  1822.          Uses DOS, CRT,
  1823.               totFAST, totIO1, totIO3, totINPUT;
  1824.  
  1825.          Var
  1826.             MyList: array[1..10] of string[60];
  1827.             WWField: WWArrayIOOBJ;
  1828.          procedure FillArray;
  1829.          {}
  1830.          begin
  1831.             FillChar(MyList,sizeof(MyList),#0);
  1832.             MyList[1] := 'It seems like we have to work at innocence ';
  1833.             MyList[2] := 'and being pure, and at the same time we have ';
  1834.             MyList[3] := 'to work at being successful so that we have ';
  1835.             MyList[4] := 'an understanding as to what the rest of the ';
  1836.             MyList[5] := 'world is up to.';
  1837.             MyList[6] := '';
  1838.             MyList[7] := 'Brother Anthony Fiore';
  1839.          end; {FillArray}
  1840.  
  1841.          begin
  1842.             ClrScr;
  1843.             Screen.WriteCenter(1,15,'Press F10 to finish');
  1844.             FillArray;
  1845.             Mouse.Show;
  1846.             with WWField do
  1847.             begin
  1848.                Init(5,7,65,7,'A Quote');
  1849.                AssignList(MyList,10,60);
  1850.  
  1851.  
  1852. Controlling User Input                                                     11-37
  1853. --------------------------------------------------------------------------------
  1854.  
  1855.                WrapFull;
  1856.                Activate;
  1857.                gotoxy(1,20);
  1858.                Done;
  1859.             end;
  1860.             Mouse.Hide;
  1861.          end.
  1862.  
  1863.  
  1864.  
  1865. WWLinkIOOBJ
  1866.          This object accesses a DLLOBJ object to determine which items to dis-
  1867.          play in the list. You must create a DLLOBJ instance, populate the list,
  1868.          and then call the following AssignList method:
  1869.  
  1870.  
  1871.          AssignList(var LinkList: DLLOBJ; Max:integer);
  1872.          This method is passed a DLLOBJ instance, or any instance of an object
  1873.          descended from DLLOBJ, e.g. StrDLLOBJ. Max specifies the maximum number
  1874.          of lines by which the Toolkit can extend the list.
  1875.  
  1876.  
  1877.          Listed below is the demo program DEMIO16.PAS, which illustrates how to
  1878.          build a WWLinkIOOBJ field.
  1879.          program DemoIOSixteen;
  1880.          {demIO16 - single WWLinkIOOBJ input}
  1881.          Uses DOS, CRT,
  1882.               totFAST, totIO1, totIO3, totINPUT, totLINK;
  1883.  
  1884.          Var
  1885.             MyList: StrDLLOBJ;
  1886.             WWField: WWLinkIOOBJ;
  1887.          procedure FillList;
  1888.          {}
  1889.          var Retcode: integer;
  1890.          begin
  1891.             with MyList do
  1892.             begin
  1893.                init;
  1894.                Retcode := Add('It seems like we have to work at innocence ');
  1895.                Retcode := Add('and being pure, and at the same time we have ');
  1896.                Retcode := Add('to work at being successful so that we have ');
  1897.                Retcode := Add('an understanding as to what the rest of the ');
  1898.                Retcode := Add('world is up to.');
  1899.                Retcode := Add('');
  1900.                Retcode := Add('Brother Anthony Fiore');
  1901.             end;
  1902.          end; {FillList}
  1903.  
  1904.  
  1905.  
  1906. 11-38                                                               User's Guide
  1907. --------------------------------------------------------------------------------
  1908.  
  1909.          begin
  1910.             ClrScr;
  1911.             Screen.WriteCenter(1,15,'Press F10 to finish');
  1912.             FillList;
  1913.             Mouse.Show;
  1914.             with WWField do
  1915.             begin
  1916.                Init(5,7,65,7,'A Quote');
  1917.                AssignList(MyList,40);
  1918.                WrapFull;
  1919.                Activate;
  1920.                gotoxy(1,20);
  1921.                MyList.Done;
  1922.                Done;
  1923.             end;
  1924.             Mouse.Hide;
  1925.          end.
  1926.  
  1927.  
  1928.          The display generated by both of the demo programs is identical, and is
  1929.          illustrated in figure 11.12.
  1930.  
  1931.  
  1932. Figure 11.12                                                            [SCREEN]
  1933. A Word Wrap
  1934. Field
  1935.  
  1936.  
  1937.  
  1938. Button Fields
  1939.          Buttons are for use with full screen input forms. They provide a way
  1940.          for the user to invoke an event. For example, an input form may have a
  1941.          SAVE button and a CANCEL button. A button can be selected by tabbing to
  1942.          the button and pressing [KEYCAP], pressing the button hotkey, or by
  1943.          clicking the mouse cursor on the button.
  1944.  
  1945.          The Toolkit provides three button objects in the totIO1 unit: Stri-
  1946.          pIOOBJ, Strip3dIOOBJ, and ButtonIOOBJ. All three objects function iden-
  1947.          tically, and the differences are purely cosmetic. The StripIOOBJ object
  1948.          provides a single-line button, Strip3dIOOBJ is a single line button
  1949.          with a black shadow, and ButtonIOOBJ displays the button text sur-
  1950.          rounded by a box. Refer back to figure 11.4 (on page 11-8) for examples
  1951.          of each button type.
  1952.          All three button objects are descended from VisibleIOOBJ and share the
  1953.          following, previously described, methods:
  1954.  
  1955.  
  1956.  
  1957. Controlling User Input                                                     11-39
  1958. --------------------------------------------------------------------------------
  1959.  
  1960.                   SetActiveStatus(Selectable:boolean);
  1961.                   SetHotkey(HK:word);
  1962.                   SetID(ID:word);
  1963.                   SetLabel(Lbl:string);
  1964.                   SetMessage(X,Y:byte;Msg:string);
  1965.                   Done;
  1966.  
  1967.  
  1968.          While the SetLabel method is technically available, it is not normally
  1969.          used, because the button text acts as a label.
  1970.          The totIO1 unit includes the declaration of the enumerated type tAc-
  1971.          tion, which has the following members: None, NextField, PrevField, Fin-
  1972.          ished, Escaped, Refresh, Signal, Enter, Help, Stop1..Stop9. All these
  1973.          members are used internally by the Toolkit to control events during
  1974.          full screen input. The following members should be used with buttons:
  1975.  
  1976.               Finished       Use with buttons to indicate a standard end of a
  1977.                              form editing session, e.g. buttons like "OK",
  1978.                              "Done", "Proceed", "Save".
  1979.               Escaped        Use with buttons that allow the user to exit
  1980.                              without processing the edited data, e.g. buttons
  1981.                              like "Cancel", "Abort".
  1982.  
  1983.               Help           Use with a "Help" button. When selected, the
  1984.                              Toolkit will automatically invoke a context sensi-
  1985.                              tive help system (discussed later).
  1986.               Stop1..Stop9   These buttons function like Finished. They should
  1987.                              be used to successfully end the form edit session.
  1988.                              They are provided so that you may provide multiple
  1989.                              finished buttons. Based on which button is
  1990.                              selected, you may process the edited data differ-
  1991.                              ently. For example, you may create the following
  1992.                              three buttons:
  1993.                                       "Save & Quit"  -  Finished
  1994.                                       "Save & Edit Next" - Stop1
  1995.                                       "Save & Backup File" - Stop2
  1996.                              Whichever button is selected, the edit session will
  1997.                              end, and the FormOBJ (discussed later) will return
  1998.                              the tAction member selected.
  1999.  
  2000.  
  2001.          All three buttons share the following method:
  2002.  
  2003.          Init(X,Y:byte;Tit:string;Act:tAction);
  2004.  
  2005.  
  2006.  
  2007. 11-40                                                               User's Guide
  2008. --------------------------------------------------------------------------------
  2009.  
  2010.          This method initializes the button and must be called first. The first
  2011.          two parameters specify the upper left (X,Y) coordinate of the button.
  2012.          The third parameter is the title which will be displayed in the button.
  2013.          The title may include embedded highlight ('~') characters. The fourth
  2014.          parameter is a member of the enumerated type tAction, which indicates
  2015.          what action to take when the button is selected.
  2016.  
  2017.  
  2018.          Listed below is an extract of the program DEMIO17.PAS. This program is
  2019.          an enhancement to DEMIO12.PAS. Two buttons have been added to the dia-
  2020.          log box. Compare the display of the new program, shown in figure 11.13,
  2021.          with the button-less version in figure 11.10 (page 11-30).
  2022.          procedure InitVars;
  2023.          {}
  2024.          begin
  2025.             {...}
  2026.             OK.Init(23,14,'   ~O~K   ',Finished);
  2027.             OK.SetHotkey(79);
  2028.             Cancel.Init(36,14,' C~a~ncel ',Escaped);
  2029.             Cancel.SetHotkey(65);
  2030.             {...}
  2031.          end; {InitVars}
  2032.  
  2033.  
  2034.  
  2035. Figure 11.13                                                            [SCREEN]
  2036. 3D Strip
  2037. Buttons
  2038.  
  2039.  
  2040.  
  2041. Controlling Defaults with IOTOT
  2042.          One of the basic approaches in the Toolkit is to default as much as
  2043.          possible! This saves you the chore of setting dozens of parameters like
  2044.          display colors every time you want to perform a simple task. You can,
  2045.          of course, change any of the default values to meet your specific
  2046.          needs.
  2047.  
  2048.          All the colors and default settings for user input are established by
  2049.          the instance IOTOT^. IOTOT is a pointer to an object of type InputOBJ
  2050.          and is designed specifically to give you control of the input defaults.
  2051.          There are methods for setting display colors, field rules, the case of
  2052.          string input, whether the fields are initially in insert mode, and so
  2053.          on.
  2054.          To modify the defaults, all you have to do is call one of the IOTOT^
  2055.          methods. Before analyzing the detailed method syntax, you need to be
  2056.          aware of the wealth of colors used by the Toolkit. Most display set-
  2057.          tings require four different color attributes to be specified. The
  2058.  
  2059.  
  2060.  
  2061. Controlling User Input                                                     11-41
  2062. --------------------------------------------------------------------------------
  2063.  
  2064.          first two attributes are used when the field is highlighted, i.e. when
  2065.          the user is editing the field, and the second two attributes are used
  2066.          when the field is not highlighted. You may recall that the Toolkit can
  2067.          display any string in two colors using the method WriteHi (discussed on
  2068.          page 5-3). Many of the strings in the IO objects also support the two
  2069.          colors capability, e.g. field labels, button text, and check boxes.
  2070.          That is why the color setting methods need to use two colors when the
  2071.          field is highlighted, and two colors when it isn't, making a total of
  2072.          four colors for each category.
  2073.  
  2074.  
  2075.  
  2076.            Don't forget that the Toolkit uses a combined foreground/back-
  2077.            ground attribute to define each color. Refer to page 3.11 for
  2078.            further information.
  2079.  
  2080.  
  2081.          The following methods can be used to change the Toolkit IO defaults:
  2082.  
  2083.          SetColLabel(Off,OffHot,On,OnHot:byte);
  2084.  
  2085.          Specifies the display attributes for labels. The first two parameters
  2086.          specify the display attributes when the field is not highlighted. The
  2087.          first parameter is the normal attribute, and the second attribute is
  2088.          the color used after the embedded highlight character, e.g. ~. The
  2089.          third and fourth parameters specify the attributes to use when the
  2090.          field is highlighted.
  2091.  
  2092.          SetColButton(Off,OffHot,On,OnHot:byte);
  2093.  
  2094.          Specifies the four display attributes for button text.
  2095.  
  2096.          SetColGroup(Off,OffHot,On,OnHot:byte);
  2097.  
  2098.          Specifies the four color attributes to use with radio button and check
  2099.          box fields.
  2100.  
  2101.          SetColList(Off,OffHot,On,OnHot:byte);
  2102.  
  2103.          Specifies the four colors to use for list fields.
  2104.  
  2105.          SetColField(Off,On,Mask,Inactive:byte);
  2106.  
  2107.          Specifies the colors to use with standard string fields. The first
  2108.          parameter is the display color when the field is not highlighted, the
  2109.          second parameter is the color when the field is highlighted, the third
  2110.          parameter is the color to display formatting characters in PictureIOOBJ
  2111.          fields, and the fourth parameter is the default display color for any
  2112.          inactive (i.e. non-selectable) field.
  2113.  
  2114.  
  2115. 11-42                                                               User's Guide
  2116. --------------------------------------------------------------------------------
  2117.  
  2118.            Note: For consistency, the Toolkit does not allow you to change
  2119.            the display attributes of an individual field on an input form.
  2120.            The attributes are always derived from IOTOT at display time. You
  2121.            must use the methods SetColLabel, SetColButton, SetColGroup, Set-
  2122.            ColList, and SetColField to change the display attributes of all
  2123.            the field types in the relevant category.
  2124.  
  2125.  
  2126.  
  2127.  
  2128.          SetColMsg(Col:byte);
  2129.  
  2130.          Sets the color of the message which is displayed when the field is
  2131.          highlighted. Specify an attribute of zero, if you want the current
  2132.          display attribute to be used.
  2133.  
  2134.          SetIns(On:boolean);
  2135.  
  2136.          Controls whether the input fields are initially in insert (True) or
  2137.          overtype (False) mode.
  2138.  
  2139.          SetRules(Rules:byte);
  2140.  
  2141.          Sets the default field rules (refer to page 11-12 for further informa-
  2142.          tion).
  2143.  
  2144.          SetPadChar(Pad:char);
  2145.  
  2146.          When a field value does not entirely fill the allotted field, the
  2147.          unused characters are represented by displaying a pad character. By
  2148.          default, this value is set to a dot (ASCII characters 250). This method
  2149.          is used to change the pad character, and one of the most common alter-
  2150.          natives is a space, e.g. IOTOT^.SetPadChar(' ');.
  2151.  
  2152.          SetJust(Just:tJust);
  2153.  
  2154.          This method is used to set the default justification of the string
  2155.          fields (see page 11.13).
  2156.  
  2157.          SetCursor(Curs: tCursPos);
  2158.  
  2159.          This method controls where the cursor is positioned when an input field
  2160.          is highlighted (see page 11.13).
  2161.  
  2162.          SetCase(Cas:tCase);
  2163.  
  2164.          This method can be used to control whether the Toolkit automatically
  2165.          adjusts the case of any of the string field objects, when the user
  2166.          leaves the field (see page 11.13).
  2167.  
  2168. Controlling User Input                                                     11-43
  2169. --------------------------------------------------------------------------------
  2170.  
  2171.          SetForceCase(On:boolean);
  2172.  
  2173.          The SetForceCase method is used to control whether the case of the
  2174.          string input is adjusted while the user is typing in the string. Pass a
  2175.          True parameter to force the case adjustment (as specified with the
  2176.          method SetCase) every time a character is pressed. Pass a False parame-
  2177.          ter if you want the string to be adjusted only when the user moves to
  2178.          another field.
  2179.  
  2180.          The following function methods return information about the current
  2181.          default settings:
  2182.  
  2183.  
  2184.          LabelCol(Element:byte): byte;
  2185.          This function method returns the current attribute for displaying field
  2186.          labels. Pass a parameter with a value between 1 and 4 to indicate which
  2187.          attribute you want to determine. The parameter values represent the
  2188.          following colors:
  2189.  
  2190.               1     Not highlighted normal attribute.
  2191.               2     Not highlighted high attribute.
  2192.               3     Highlighted normal attribute.
  2193.               4     Highlighted high attribute.
  2194.  
  2195.          ButtonCol(Element:byte): byte;
  2196.  
  2197.          Returns the attribute byte of the Button text.
  2198.  
  2199.          GroupCol(Element: byte): byte;
  2200.  
  2201.          Returns the attribute byte of radio button and check box fields.
  2202.  
  2203.          ListCol(Element:byte): byte;
  2204.  
  2205.          Returns the attribute byte of the list fields.
  2206.  
  2207.          FieldCol(Element:byte): byte;
  2208.  
  2209.          Returns the attribute byte of the string fields. Pass a parameter with
  2210.          a value between 1 and 4 to indicate which attribute you want to deter-
  2211.          mine. The parameter values represent the following colors:
  2212.               1     Highlighted attribute.
  2213.               2     Not highlighted attribute.
  2214.               3     Attribute of mask character in picture fields.
  2215.               4     Attribute of inactive (non-selectable) fields.
  2216.  
  2217.  
  2218.          MessageCol: byte;
  2219.  
  2220.  
  2221. 11-44                                                               User's Guide
  2222. --------------------------------------------------------------------------------
  2223.  
  2224.          Returns the attribute used for writing the highlighted field's message.
  2225.  
  2226.  
  2227.          InputPadChar: char;
  2228.          Returns that character which is used to fill a field when the input is
  2229.          shorter than the field length.
  2230.  
  2231.  
  2232.          InputJust: tJust;
  2233.          Returns the default string justification (see page 11-13)
  2234.  
  2235.  
  2236.          InputCursorLoc: tCursPos;
  2237.          Returns the default cursor position (see page 11-13).
  2238.  
  2239.  
  2240.          InputCase: tCase;
  2241.          Returns the default case setting for string fields (see page 11-13).
  2242.  
  2243.  
  2244.          InputForceCase: boolean;
  2245.          Returns true if user input is forced to a specific case when each
  2246.          character is input.
  2247.  
  2248.  
  2249.          If you want to reset all the IOTOT settings back to the original Tool-
  2250.          kit defaults, all you have to do is call the SetDefaults method as
  2251.          follows:
  2252.                   IOTOT^.SetDefaults;
  2253.  
  2254.          By looking at the actual Toolkit code for the SetDefaults method, you
  2255.          can quickly determine the default values.
  2256.          procedure InputOBJ.SetDefaults;
  2257.          {}
  2258.          begin
  2259.             if Monitor^.ColorOn then {color System}
  2260.             begin
  2261.                SetColLabel(78,76,79,76);
  2262.                SetColButton(32,46,47,46);
  2263.                SetColGroup(48,62,63,62);
  2264.                SetColList(48,62,31,30);
  2265.                SetColField(48,31,23,71);
  2266.             end
  2267.             else
  2268.             begin
  2269.                SetColLabel(112,126,127,126);
  2270.                SetColButton(32,46,47,46);
  2271.                SetColGroup(48,62,63,62);
  2272.  
  2273.  
  2274. Controlling User Input                                                     11-45
  2275. --------------------------------------------------------------------------------
  2276.  
  2277.                SetColList(48,62,31,30);
  2278.                SetColField(48,31,23,24);
  2279.             end;
  2280.             SetColMsg(0);
  2281.             vInputPad := chr(250);
  2282.             vCase := Leave;
  2283.             vForceCase := false;
  2284.             vInputJust :=  JustLeft;
  2285.             vCursorLoc := CursPrev;
  2286.             vInsert := false;
  2287.             vRules :=  AllowNull;
  2288.          end; {InputOBJ.SetDefaults}
  2289.  
  2290.  
  2291.  
  2292. Form Management
  2293.          In this section, the various techniques for combining a collection of
  2294.          fields into a form will be explained. You have already learned the
  2295.          complicated stuff! All you have to do is create a FormOBJ instance and
  2296.          tell it which field object to include in the form.
  2297.  
  2298.          FormOBJ is the form manager and is located in the totIO1 unit. To build
  2299.          a form, initialize the FormOBJ instance, add the fields that will
  2300.          create the form, and instruct the Toolkit to process the user input.
  2301.          The following FormOBJ methods perform these services:
  2302.  
  2303.          Init;
  2304.  
  2305.          This method initializes the FormOBJ instance, and should always be
  2306.          called first.
  2307.  
  2308.          AddItem(var NewItem: ItemIOOBJ);
  2309.  
  2310.          This method should be called once for every field on the form. The only
  2311.          passed parameter is an object descended from ItemIOOBJ, i.e. any of the
  2312.          objects discussed so far in this chapter.
  2313.  
  2314.          Go:tAction;
  2315.  
  2316.          Having added all the items, call the function method Go to activate the
  2317.          form, and process the user's input. The function returns one of the
  2318.          following members of the enumerated type tAction: Finished, Escaped,
  2319.          Stop1 through Stop9. The value returned will depend on which button or
  2320.          key the user pressed. Based on the return value, you can decide how to
  2321.          process the user-entered data.
  2322.  
  2323.  
  2324.  
  2325. 11-46                                                               User's Guide
  2326. --------------------------------------------------------------------------------
  2327.  
  2328.          In addition to the standard user input fields, the totIO1 unit includes
  2329.          a special object, ControlKeysIOOBJ, which is used to control how the
  2330.          user moves between fields and terminates input. Every form you create
  2331.          should include a ControlKeysIOOBJ instance. ControlKeysIOOBJ objects
  2332.          provide the following three methods:
  2333.  
  2334.  
  2335.          Init;
  2336.          This method initializes the object and must be called first. The object
  2337.          actually provides the Toolkit with four special keys: the key to move
  2338.          on to the next field, the key to move back to the previous field, the
  2339.          key to finish the edit session, and the key to abort the edit session.
  2340.          When the ControlIOOBJ object is initialized, these keys are set to
  2341.          [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP], respectively.
  2342.  
  2343.  
  2344.          SetKeys(Next,Prev,Fin,Esc:word);
  2345.          This method is used to override the default keys. The method is passed
  2346.          the four key codes which represent the keys for moving to the next
  2347.          field, moving back to the previous field, to finish editing, and to
  2348.          abort editing. For example, the statement
  2349.  
  2350.                  SetKeys(336,328,335,27);
  2351.  
  2352.          will set the keys to [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP]. Be
  2353.          careful which keys you select. For example, if you have a word wrap
  2354.          field, you probably don't want to use the up and down arrows. Each time
  2355.          the user presses the down arrow to edit the next line, he/she will jump
  2356.          to the next field!
  2357.  
  2358.  
  2359.          Done;
  2360.          This should be called to dispose of the object when it is no longer
  2361.          required.
  2362.  
  2363.  
  2364.  
  2365.          Listed below is the example DEMIO2.PAS, which was first introduced at
  2366.          the beginning of the chapter. It shows how to use some of these basic
  2367.          FormOBJ methods. Refer back to figure 11.2 on page 11-4 to see the
  2368.          resultant output.
  2369.  
  2370.          program DemoIOTwo;
  2371.          {demIO2 - full field input}
  2372.          Uses DOS, CRT,
  2373.               totFAST, totIO1, totIO2;
  2374.  
  2375.  
  2376.  
  2377. Controlling User Input                                                     11-47
  2378. --------------------------------------------------------------------------------
  2379.  
  2380.          Var
  2381.             Name: LateralIOOBJ;
  2382.             Phone: PictureIOOBJ;
  2383.             Price: FixedRealIOOBJ;
  2384.             Keys: ControlkeysIOOBJ;
  2385.             Manager: FormOBJ;
  2386.             Result: tAction;
  2387.  
  2388.          procedure InitVars;
  2389.          {}
  2390.          begin
  2391.             with Name do
  2392.             begin
  2393.                Init(35,5,20,40);
  2394.                SetLabel('Vendor Name');
  2395.             end;
  2396.             with Phone do
  2397.             begin
  2398.                Init(35,7,'(###) ###-####');
  2399.                SetLabel('Tel');
  2400.             end;
  2401.             with Price do
  2402.             begin
  2403.                Init(35,9,8,2);
  2404.                SetLabel('Unit Price');
  2405.                SetValue(250.0);
  2406.                SetMinMax(0.1,12250.0);
  2407.                SetRules(EraseDefault);
  2408.             end;
  2409.             Keys.Init;
  2410.          end; {InitVars}
  2411.          begin
  2412.             ClrScr;
  2413.             Screen.TitledBox(15,3,65,11,76,79,78,2,' Quicky Input Demo ');
  2414.             Screen.WriteCenter(25,white,'Press TAB to switched fields and
  2415.                                          press ESC or F10 to end');
  2416.             InitVars;
  2417.             with Manager do
  2418.             begin
  2419.                Init;
  2420.                AddItem(Keys);
  2421.                AddItem(Name);
  2422.                AddItem(Phone);
  2423.                AddItem(Price);
  2424.                Result := Go;
  2425.                if Result = Finished then
  2426.                   {update the database..}
  2427.                else
  2428.  
  2429.  
  2430.  
  2431. 11-48                                                               User's Guide
  2432. --------------------------------------------------------------------------------
  2433.  
  2434.                   {call Esc routine};
  2435.             end;
  2436.          end.
  2437.  
  2438.  
  2439.  
  2440.          The order in which the fields are added using AddItem will be the order
  2441.          in which the user will jump from field to field. The following FormOBJ
  2442.          method can be used to control which field is highlighted when the Go
  2443.          method is called:
  2444.  
  2445.  
  2446.          SetActiveItem(ID:word);
  2447.          This method instructs the Toolkit on which field to highlight first.
  2448.          The only parameter is the field ID of the field to be highlighted.
  2449.          Don't forget that any field can have a unique ID by calling the method
  2450.          SetID. By default, all fields have an ID of zero.
  2451.  
  2452.  
  2453. Hotkey Fields
  2454.  
  2455.          By now, you should know that any field can have a hotkey assigned with
  2456.          the method SetHotKey. There is one remaining type of field that has not
  2457.          yet been discussed. Namely, HotkeyIOOBJ objects. These fields are "in-
  2458.          visible" and are used to add special Hotkeys to the form.
  2459.          HotkeyIOBJ objects only have the following two methods:
  2460.  
  2461.  
  2462.          Init(HK:word;Act:tAction);
  2463.          A HotkeyIOOBJ object has only two properties. It has a keycode, which
  2464.          represents the key that must be pressed to invoke it, and it has an
  2465.          action code of type tAction, i.e. None, NextField, PrevField, Finished,
  2466.          Escaped, Refresh, Signal, Enter, Help, Stop1..Stop9. Whenever the user
  2467.          presses the assigned hotkey, the specified action is invoked. For exam-
  2468.          ple, if you want to assign the key [KEYCAP] (in addition to [KEYCAP])
  2469.          to end the edit session, you would initialize a HotkeyIOOBJ instance as
  2470.          follows: Init(301,Finished);
  2471.  
  2472.  
  2473.          Done;
  2474.          This disposes of the object.
  2475.  
  2476.  
  2477.  
  2478.  
  2479. Moveable Forms
  2480.          The object WinFormOBJ is a descendant of FormOBJ, and provides the same
  2481.          services with one important enhancement. WinFormOBJ manages an input
  2482.  
  2483.  
  2484. Controlling User Input                                                     11-49
  2485. --------------------------------------------------------------------------------
  2486.  
  2487.          form on a moveable window. It is ideal for creating moveable dialog
  2488.          boxes. The Toolkit itself takes advantage of WinFormOBJ to create the
  2489.          pop-up message objects and the moveable directory dialog box.
  2490.  
  2491.          WinFormOBJ inherits the following methods from FormOBJ:
  2492.                   Init;
  2493.                   AddItem(var NewItem: ItemIOOBJ);
  2494.                   Done;
  2495.  
  2496.          Additionally, WinFormOBJ has a function method Win which returns a
  2497.          pointer to the MoveWinOBJ instance on which the form is built. To
  2498.          modify the window size and other properties, just call Win^.method,
  2499.          where method is any MoveWinOBJ instance.
  2500.          If you are going to create a window-based form using WinFormOBJ, be
  2501.          sure to create each individual field objects with relative (X,Y) coor-
  2502.          dinates. In other words, the top left of the form window will be at
  2503.          coordinates (1,1).
  2504.  
  2505.          Important Note: before calling the method Go, call the method Draw.
  2506.          This instructs the WinFormOBJ object to display the window and save the
  2507.          underlying screen contents.
  2508.          Refer to the on-disk example DEMIO18.PAS for a full example illustrat-
  2509.          ing the WinFormOBJ object. DEMIO18.PAS is actually an enhancement to
  2510.          the program DEMIO17.PAS, creating a text-search dialog box.
  2511.  
  2512.  
  2513.  
  2514. Determining User Input
  2515.          When the user has edited the form, you probably want to know what data
  2516.          was entered! First, be sure to check the tAction code returned by the
  2517.          FormOBJ method Go. This will indicate whether the user escaped, or
  2518.          really wanted the data processed.
  2519.  
  2520.          The only form input objects which update the original data source are
  2521.          the word wrapping objects WWArrayIOOBJ and WWLinkIOOBJ. The Toolkit
  2522.          automatically modifies the data passed to these objects. In all other
  2523.          cases, you should call each individual object's GetValue method to
  2524.          determine the user's input.
  2525.          Review the demo programs DEMIO5,8,10,13,14 to see examples of how to
  2526.          determine user input. Also, the demo programs in the last section More
  2527.          Examples! provide still further examples.
  2528.  
  2529.  
  2530.  
  2531. 11-50                                                               User's Guide
  2532. --------------------------------------------------------------------------------
  2533.  
  2534. Advanced Techniques
  2535.  
  2536.          For the majority of situations, you have learned all you need to know
  2537.          to master form input. However, the Toolkit provides another level of
  2538.          sophistication for developers who really want to customize their input
  2539.          forms. Although this section is called Advanced Features, it does not
  2540.          mean that these features are complicated. The only reason for separa-
  2541.          ting them into a special section is because you will probably use them
  2542.          less frequently.
  2543.          There follows descriptions of how to intercept every character that is
  2544.          pressed, how to validate individual fields before allowing the user to
  2545.          leave, and how to implement a help system. The concept of raising sig-
  2546.          nals between dependent fields is also introduced.
  2547.  
  2548.  
  2549. Intercepting Every Character Press
  2550.  
  2551.          Many of the Toolkit's units include character hooks, which provide a
  2552.          way for you to nominate a procedure or function to be called every time
  2553.          a character is pressed. This allows you to intercept each character and
  2554.          if appropriate, invoke a special routine. You can even change the value
  2555.          of the character pressed. The FormOBJ and WinFormOBJ objects also pro-
  2556.          vide a character hook facility.
  2557.          A character hook is an external procedure which is called every time a
  2558.          key or mouse button is pressed. To utilize the character hook facility,
  2559.          all you have to do is create a function following some specific rules,
  2560.          and then call the FormOBJ method SetCharHook to instruct the Toolkit to
  2561.          use your function.
  2562.  
  2563.          For a function to be eligible as a character hook it must adhere to the
  2564.          following rules:
  2565.          Rule 1     The function must be declared as a FAR function. This can be
  2566.                     achieved by preceding the function with a {$F+} compiler
  2567.                     directive, and following the function with a {$F-} direc-
  2568.                     tive. Alternatively, Turbo 6 users can use the new keyword
  2569.                     FAR following the function statement.
  2570.  
  2571.          Rule 2     The function must be declared with four passed parameters.
  2572.                     Parameter one must be a variable parameter of type word.
  2573.                     This parameter indicates which key the user just pressed,
  2574.                     and you may change the value of this parameter to return a
  2575.                     different key. The second and third parameters must be
  2576.                     variable parameters of type byte, and they represent the X
  2577.                     and Y coordinates of the mouse at the time the key was
  2578.                     pressed. The fourth parameter is a variable, and must be of
  2579.                     type word. This parameter indicates the field ID of the
  2580.                     currently active field. This field can be changed to another
  2581.                     ID if you want the user to jump to a different field.
  2582.  
  2583.  
  2584.  
  2585. Controlling User Input                                                     11-51
  2586. --------------------------------------------------------------------------------
  2587.  
  2588.          Rule 3     The function must return a value of type tAction. This is an
  2589.                     enumerated type which indicates to the Toolkit how to
  2590.                     proceed. The members of the enumerated type are: None,
  2591.                     NextField, PrevField, Finished, Escaped, Refresh, Signal,
  2592.                     Enter, Help, Stop1..Stop9. If you want the edit session to
  2593.                     terminate, return Finished, Escaped, or Stop1 through Stop9.
  2594.                     If you have changed, inserted, or deleted any items in the
  2595.                     visible list, return Refresh. The Toolkit will then re-
  2596.                     display the entire form contents.
  2597.  
  2598.          Rule 4     The function must be at the root level, i.e. the function
  2599.                     cannot be nested within another procedure or function.
  2600.          The following function declaration follows these rules:
  2601.  
  2602.                   {$F+}
  2603.                   function MyCharHook(var K:word;
  2604.                                       var X,Y: byte;
  2605.                                       var FieldID:word): tAction;
  2606.                   begin
  2607.                   ...{function statements}
  2608.                      MyCharHook := NextField;
  2609.                   end;
  2610.                   {$F-}
  2611.  
  2612.          The following method SetCharHook is then called to instruct the Toolkit
  2613.          to call your function every time a key is pressed:
  2614.  
  2615.  
  2616.          SetCharHook(Func:CharFunc);
  2617.          This method is passed the function name of a function declared using
  2618.          the rules outlined above, e.g. SetCharHook(MyCharHook);.
  2619.  
  2620.  
  2621.          Listed below is an extract from the demo program DEMIO19.PAS. This file
  2622.          is a variation on our old favorite DEMIO2.PAS. In this case, a charac-
  2623.          ter hook has been added to intercept the key [KEYCAP]. If this key is
  2624.          pressed, a message showing the current time is displayed. Notice that
  2625.          if [KEYCAP] is pressed, the hook function replaces the actual key with
  2626.          a value of 0. This stops the active field from trying to process the
  2627.          key - a zero key is ignored by the Toolkit. Finally, the hook function
  2628.          returns a value of None, indicating that the form manager does not need
  2629.          to take special action.
  2630.          {$F+}
  2631.          function ShowTime(var K:word; var X,Y:byte; var ID:word):tAction;
  2632.          {}
  2633.          var Msg:  MessageOBJ;
  2634.          begin
  2635.             if K = 276 then {Alt-T}
  2636.  
  2637.  
  2638.  
  2639.  
  2640. 11-52                                                               User's Guide
  2641. --------------------------------------------------------------------------------
  2642.  
  2643.             begin
  2644.                with Msg do
  2645.                begin
  2646.                   Init(1,'The Time M''Lord');
  2647.                   Addline('');
  2648.                   AddLine(padcenter(CurrentTime,25,' '));
  2649.                   AddLine('');
  2650.                   Show;
  2651.                   Done;
  2652.                end;
  2653.                K := 0;
  2654.             end;
  2655.             ShowTime := none;
  2656.          end; {ShowTime}
  2657.          {$F-}
  2658.  
  2659.          begin
  2660.             {...}
  2661.             with Manager do
  2662.             begin
  2663.                Init;
  2664.                AddItem(Keys);
  2665.                AddItem(Name);
  2666.                AddItem(Phone);
  2667.                AddItem(Price);
  2668.                SetCharHook(ShowTime);
  2669.                Result := Go;
  2670.                {...}
  2671.             end;
  2672.          end.
  2673.  
  2674.  
  2675. Validating Input
  2676.  
  2677.          As well as a character hook, the FormOBJ objects provide leave field
  2678.          and enter field hooks. These functions are called when the user tries
  2679.          to leave a field, and when the user tries to enter a field. The leave
  2680.          field hook provides a way to ensure the contents of a field are valid
  2681.          before moving to another field. The enter field hook can be used to
  2682.          take some action before entering a field, e.g. display a warning mes-
  2683.          sage, or move the user to another field if a specific condition is not
  2684.          met.
  2685.          Like the character hook, both field hooks must adhere to the following
  2686.          common rules:
  2687.  
  2688.          Rule 1     The function must be declared as a FAR function.
  2689.  
  2690.  
  2691.  
  2692. Controlling User Input                                                     11-53
  2693. --------------------------------------------------------------------------------
  2694.  
  2695.          Rule 2     The function must return a value of type tAction. This is an
  2696.                     enumerated type, which indicates to the Toolkit how to
  2697.                     proceed.
  2698.  
  2699.          Rule 3     The function must be at the root level.
  2700.  
  2701.  
  2702.          The hooked procedure's passed parameters are different for each hook
  2703.          type, as follows:
  2704.          Leave      The function must be declared with one variable passed
  2705.                     parameter of type word. This parameter represents the field
  2706.                     ID of the field the user is leaving. This parameter can be
  2707.                     changed to another field to instruct the Toolkit to jump to
  2708.                     a different field.
  2709.  
  2710.          Enter      The function must be declared with two passed parameters.
  2711.                     The first parameter is a variable parameter of type word.
  2712.                     This parameter identifies the ID of the field the user is
  2713.                     about to enter. This parameter may be modified, to instruct
  2714.                     the Toolkit to jump to a different field. The second parame-
  2715.                     ter is of type word, and it represents the ID of the field
  2716.                     the user just left.
  2717.          Listed below are two code sample procedures which adhere to the rules
  2718.          for leave and enter field hooks.
  2719.  
  2720.                   {$F+}
  2721.                   function MyEnterHook(var NewID:word; LastID: word):tAction
  2722.                   begin
  2723.                   ...{function statements}
  2724.                      MyEnterHook := none;
  2725.                   end;
  2726.                   {$F-}
  2727.  
  2728.                   {$F+}
  2729.                   function MyLeaveHook(var LastID: word):tAction
  2730.                   begin
  2731.                   ...{function statements}
  2732.                      MyLeaveHook := none;
  2733.                   end;
  2734.                   {$F-}
  2735.  
  2736.          The FormOBJ methods SetLeaveHook or SetEnterHook can then be called to
  2737.          instruct the Toolkit to call the specified function whenever a user
  2738.          tries to leave or enter a field.
  2739.  
  2740.  
  2741.  
  2742. 11-54                                                               User's Guide
  2743. --------------------------------------------------------------------------------
  2744.  
  2745. Context Sensitive Help
  2746.  
  2747.          The fourth category of FormOBJ user hooks is the Help hook. The Help
  2748.          hook provides a way of implementing context sensitive help into your
  2749.          form.
  2750.          To implement a help hook, all you have to do is create a procedure
  2751.          following some specific rules, and then call the FormOBJ method SetHel-
  2752.          pHook to instruct the Toolkit to use your function.
  2753.  
  2754.          For a function to be eligible as a character hook it must adhere to the
  2755.          following rules:
  2756.          Rule 1     The procedure must be declared as a FAR procedure.
  2757.  
  2758.          Rule 2     The procedure must be declared with a single passed parame-
  2759.                     ter of type word. This parameter identifies the ID of the
  2760.                     highlighted field at the time the user requested help.
  2761.          Rule 3     The procedure must be at the root level.
  2762.  
  2763.          The following code fragment shows a procedure which adheres to these
  2764.          rules.
  2765.                   {$F+}
  2766.                   function MyHelpHook(LastID: word);
  2767.                   begin
  2768.                   ...{help display statements}
  2769.                   end;
  2770.                   {$F-}
  2771.  
  2772.  
  2773.          If you go to the trouble of creating a help system, you ought to give
  2774.          the user some way of requesting help! The two best ways to add help are
  2775.          with a hotkey and with a help button. Either way is easy, and you ought
  2776.          to consider using both. The following code fragment shows how to imple-
  2777.          ment them:
  2778.          var
  2779.            HelpBut: Strip3dIOOBJ;
  2780.            F1key: HotkeyIOOBJ;
  2781.  
  2782.          begin
  2783.             {...}
  2784.             HelpBut.Init(34,12,'  ~H~elp  ',Help);
  2785.             HelpBut.SetHotkey(291);
  2786.             HelpBut.SetID(HelpID);
  2787.             F1Key.Init(315,Help);
  2788.             {...}
  2789.          end.
  2790.  
  2791.  
  2792.  
  2793. Controlling User Input                                                     11-55
  2794. --------------------------------------------------------------------------------
  2795.  
  2796.          Notice that the help button is assigned an ID of HelpID. HelpID is a
  2797.          constant defined in the totIO1 unit. The likelihood is that the user
  2798.          wants help on the highlighted field, and doesn't actually want to move
  2799.          to the help button. By assigning an object an ID of HelpID, the Toolkit
  2800.          knows not to swap to it when it is selected with a mouse button or
  2801.          hotkey.
  2802.  
  2803.          Refer to the demo program DEMIO20.PAS for a full example of how to
  2804.          implement a help system. This program is a further enhancement to the
  2805.          search dialog box demo program discussed earlier. Figure 11.14 illus-
  2806.          trates the display generated when the user asks for help.
  2807.  
  2808.  
  2809. Figure 11.14                                                            [SCREEN]
  2810. Add a Help
  2811. System
  2812.  
  2813.  
  2814. Creating Descendant Objects
  2815.  
  2816.          The FormOBJ object provides four different hooks for customizing the
  2817.          form input to meet your specific needs. If you think there may be an
  2818.          OOP way to achieve the same results you are right. You can create a
  2819.          descendent object from either FormOBJ or WinFormOBJ, and replace the
  2820.          following virtual methods:
  2821.          function CharTask(var K:word; var X,Y:byte;var FieldID:word):tAction;
  2822.          function LeaveTask(var FieldID:word):tAction;
  2823.          function EnterTask(var NewID:word; OldID;word):tAction;
  2824.          procedure HelpTask(ID:word);
  2825.  
  2826.          The passed parameters to these virtual methods are exactly the same as
  2827.          the ones described earlier for the hooks.
  2828.          Refer to chapter 9: Managing Lists page 9-32 for a comparison of hooks
  2829.          and virtual methods.
  2830.  
  2831.  
  2832.          In some special circumstances you will want to create fields which
  2833.          interact. A good example can be found in the Toolkit object DirWinOBJ
  2834.          (discussed in chapter 10). This object has three main fields -  a
  2835.          filename input field, a list of matching files, and a list of directo-
  2836.          ries and drives. If the user enters a new file mask, the file list
  2837.          needs to be refreshed. Similarly, if the user changes directories, the
  2838.          file list and the directory list need to be updated.
  2839.  
  2840.          The solution is for the modified field to raise a signal when changes
  2841.          need to be made to other fields. When a field raises a signal, the
  2842.          Toolkit passes the signal to every other field in turn, and each of
  2843.          these fields may itself raise signals. Every input field object has the
  2844.          following virtual methods:
  2845.  
  2846.  
  2847.  
  2848. 11-56                                                               User's Guide
  2849. --------------------------------------------------------------------------------
  2850.  
  2851.          procedure RaiseSignal(var TheSig:tSignal);
  2852.          procedure HandleSignal(var BaseSig:tSignal; var NewSig:tSignal);
  2853.          procedure ShutDownSignal(var BaseSig:tSignal);
  2854.  
  2855.          Refer to Part 2: Extending the Toolkit for further information about
  2856.          creating input objects which raise and handle signals.
  2857.  
  2858.  
  2859. More Examples!
  2860.  
  2861.          There are several additional on-disk examples included in the Toolkit.
  2862.          These examples combine many of the features described in this chapter
  2863.          to provide powerful input routines. For example, IODEM21.PAS shows how
  2864.          you might use the objects to create a database access program, and
  2865.          IODEM22.PAS illustrates how you can use PgUp and PgDn to implement a
  2866.          double input screen.
  2867.